n8n 中文文档

用代码创建你的第一个工作流

在本教程中,你将使用 Workflow SDK 编写一个工作流文件,用 validate_workflow 检查它,并用 create_workflow_from_code 将其保存到你的实例。

提示

给编码代理的提示词

连接到 n8n MCP 服务器,调用 get_workflow_sdk_reference,然后为下文描述的工作流编写 Workflow SDK 文件。使用完整代码调用 validate_workflow,修复 hint 指出的每个错误,然后调用 create_workflow_from_code 并返回工作流 URL。

你需要准备什么

  • 一个已启用 MCP 访问的 n8n 实例,以及一个已连接到该实例的 MCP 客户端。客户端连接示例涵盖了 Claude Code、Claude Desktop 和 Cursor。
  • 无需本地安装,由实例解析代码。

你将学到什么

  • Workflow SDK 文件的结构。
  • 如何在创建工作流之前检查代码。
  • 如何添加分支。

编写工作流文件

创建包含以下内容的 github-stars.ts。它包含一个手动触发器、一个 HTTP Request 节点和一个 Edit Fields (Set) 节点:

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);

需要记住三条规则:

  • 先声明每个节点,最后再组合工作流。
  • 使用编辑器所用的节点类型 id 和 version。MCP 服务器上的 search_nodes 和 get_node_types 会返回它们。
  • 用 expr() 包裹表达式。其中的文本与编辑器中的相同。

检查代码

让你的 MCP 客户端调用 validate_workflow,并将完整文件作为 code 参数传入。有效的文件会返回:

{ "valid": true, "nodeCount": 3 }

如果 valid 为 false,响应中会包含 errors 列表,通常还会有 hint。按照提示修复问题,然后再次运行该工具。常见原因包括缺少 export default、节点 version 错误,或使用了节点不具备的参数。

创建工作流

使用相同的 code 调用 create_workflow_from_code。响应中包含 workflowId 和 url。打开该 URL,在编辑器中运行一次工作流,并检查 Keep stars 节点是否输出了 stars 字段。

该工具会将它在实例上找到的凭据分配给需要凭据的节点。它会跳过 HTTP Request 节点,因此如果你调用的 API 需要凭据,请手动为该节点设置凭据。

添加分支

将 Keep stars 节点替换为一个 If 节点,让热门仓库走一条路径,其余仓库走另一条路径。为每个分支添加一个 Edit Fields 节点。每个 If 条件都需要 options、conditions 和 combinator。完整文件如下:

import { workflow, node, trigger, ifElse, 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 isPopular = ifElse({
  version: 2.2,
  config: {
    name: 'Is popular?',
    parameters: {
      conditions: {
        options: { caseSensitive: true, leftValue: '', typeValidation: 'strict' },
        conditions: [
          { leftValue: expr('{{ $json.stargazers_count }}'), operator: { type: 'number', operation: 'gt' }, rightValue: 100000 }
        ],
        combinator: 'and'
      }
    }
  }
});

const markPopular = node({
  type: 'n8n-nodes-base.set',
  version: 3.4,
  config: {
    name: 'Mark popular',
    parameters: {
      mode: 'manual',
      includeOtherFields: false,
      assignments: {
        assignments: [
          { id: 'popular', name: 'popular', value: true, type: 'boolean' },
          { id: 'stars', name: 'stars', value: expr('{{ $json.stargazers_count }}'), type: 'number' }
        ]
      }
    }
  }
});

const markNotPopular = node({
  type: 'n8n-nodes-base.set',
  version: 3.4,
  config: {
    name: 'Mark not popular',
    parameters: {
      mode: 'manual',
      includeOtherFields: false,
      assignments: {
        assignments: [
          { id: 'popular', name: 'popular', value: false, type: 'boolean' },
          { id: 'stars', name: 'stars', value: expr('{{ $json.stargazers_count }}'), type: 'number' }
        ]
      }
    }
  }
});

export default workflow('github-stars', 'GitHub stars')
  .add(start)
  .to(fetchRepo)
  .to(isPopular
    .onTrue(markPopular)
    .onFalse(markNotPopular));

每个分支都是一条完整路径:可以在 .onTrue() 或 .onFalse() 中使用 .to() 串联更多节点。

要修改你已创建的工作流,不要再创建第二个。请使用工作流 ID 和由部分更改(例如 addNode 或 updateNodeParameters)组成的 operations 数组调用 update_workflow。工具参考列出了所有操作。

后续步骤

  • 阅读你的实例提供的完整参考:在 n8n MCP 服务器上调用 get_workflow_sdk_reference。patterns 部分包含循环、并行分支、多个触发器和 AI 代理的完整示例。
  • 使用 technique: "list" 调用 get_workflow_best_practices,查看有指南的用例,例如聊天机器人、调度和数据提取。
  • 如需在不使用 MCP 服务器的情况下将代码转换为工作流 JSON,请参阅 SDK README。
  • 使用使用 AI 构建设置你的编码代理。
不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。