n8n 中文文档

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 版本对应的构建器函数、语言规则、模式和表达式。

本节内容

  • 快速入门:编写你的第一个工作流文件,检查它,并在实例上创建它。
  • 使用 AI 构建:AI 编码代理为你的实例编写 Workflow SDK 代码所需的全部内容。

这是哪个 package

@n8n/workflow-sdk 用于描述工作流。它不是 n8n 公共 API 客户端,不是 @n8n/cli 命令行工具,也不是用于构建自定义节点的框架。走 MCP 方式时你无需安装它,因为由 n8n 实例解析代码。如果你想在本地转换代码,或在编辑器中获得 TypeScript 类型,请安装它。

Workflow SDK 适用于 n8n Cloud 和自托管实例。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。