Workflow SDK
Workflow SDK 让你以代码形式描述 n8n 工作流。你声明触发器和节点,使用 .add() 和 .to() 将它们连接起来,然后导出结果。SDK 会将这些代码转换为编辑器所使用的同一种工作流 JSON,并对其进行验证。
SDK 代码是 TypeScript 的一个受限子集。n8n 使用解释器读取它,代码本身永远不会运行。
提示
功能可用性
n8n MCP 服务器上的 Workflow SDK 构建器工具从 n8n 2.12.0 起可用。SDK 是 npm 上的 @n8n/workflow-sdk package。使用 MCP 构建器工具无需安装它。
谁在使用 Workflow SDK
n8n 中有三个部分会读取 Workflow SDK 代码:
- n8n MCP 服务器的构建器工具。
validate_workflow检查代码,create_workflow_from_code将其保存为工作流,update_workflow修改现有工作流。请参阅 MCP 服务器工具参考。 - n8n AI,它在为你构建工作流时会编写 Workflow SDK 代码。
- Claude Code 或 Cursor 等 AI 编码代理,在连接到 n8n MCP 服务器时会使用它。
将代码转换为工作流
有两种方式可以将 SDK 代码转换为实例上的工作流:
- 通过 n8n MCP 服务器。 将代码发送给
validate_workflow,然后发送给create_workflow_from_code。实例会解析代码,因此你无需安装任何东西。这需要 n8n 2.12.0 或更高版本,并且 owner 或 admin 必须先启用 MCP 访问。快速入门将逐步介绍这种方式。 - 在本地使用 package。 从 npm 安装
@n8n/workflow-sdk。使用parseWorkflowCodeToBuilder将代码转换为工作流 JSON,然后使用validateWorkflowBuilder进行检查。之后,使用 n8n API 或 n8n CLI 根据该 JSON 创建工作流。解析器不接受import行,因此请在解析前将其删除。请参阅 SDK README 中的将代码转换为工作流 JSON。
n8n API 和 n8n CLI 处理的是工作流 JSON,它们不会读取 SDK 代码。
代码是什么样子
工作流是一串链式调用。以下示例运行一个手动触发器,获取一个 GitHub 仓库,并保留其 star 数量:
import { workflow, node, trigger, expr } from '@n8n/workflow-sdk';
const start = trigger({
type: 'n8n-nodes-base.manualTrigger',
version: 1,
config: { name: 'Start' }
});
const fetchRepo = node({
type: 'n8n-nodes-base.httpRequest',
version: 4.3,
config: {
name: 'Fetch repository',
parameters: { method: 'GET', url: 'https://api.github.com/repos/n8n-io/n8n' }
}
});
const keepStars = node({
type: 'n8n-nodes-base.set',
version: 3.4,
config: {
name: 'Keep stars',
parameters: {
mode: 'manual',
includeOtherFields: false,
assignments: {
assignments: [
{ id: 'stars', name: 'stars', value: expr('{{ $json.stargazers_count }}'), type: 'number' }
]
}
}
}
});
export default workflow('github-stars', 'GitHub stars')
.add(start)
.to(fetchRepo)
.to(keepStars);
每个文件都通过 export default workflow(...) 导出一个工作流。节点类型和参数名称与工作流 JSON 中的相同。表达式使用 expr() 包裹你在编辑器中熟悉的 {{ }} 语法。
SDK 参考
SDK 参考与 SDK 代码放在一起:
- SDK README 介绍了如何安装 package、一个可运行的示例,以及如何将代码转换为工作流 JSON。
- 如需完整参考,请在 n8n MCP 服务器上调用
get_workflow_sdk_reference。它会返回与你的实例所运行的 SDK 版本对应的构建器函数、语言规则、模式和表达式。
本节内容
这是哪个 package
@n8n/workflow-sdk 用于描述工作流。它不是 n8n 公共 API 客户端,不是 @n8n/cli 命令行工具,也不是用于构建自定义节点的框架。走 MCP 方式时你无需安装它,因为由 n8n 实例解析代码。如果你想在本地转换代码,或在编辑器中获得 TypeScript 类型,请安装它。
Workflow SDK 适用于 n8n Cloud 和自托管实例。
相关资源
不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。