使用 n8n-node 工具#

n8n-node 工具是用于开发 n8n 社区节点的官方 CLI。您可以使用它来快速搭建新节点、构建项目并在开发过程中运行节点。

通过 n8n-node，您可以创建符合已验证社区节点指南的节点。

获取 n8n-node#

无需安装直接运行 n8n-node#

您可以直接创建 n8n-node 项目而无需安装，只需通过包管理器使用 @n8n/create-node 初始化工具：

npm create @n8n/node@latest

这将在本地建立初始项目文件（替代在本地安装 n8n-node 并显式运行 new 命令的方式）。之后，您可以通过项目目录内的包管理器脚本运行器执行其余 n8n-node 命令（例如 npm run dev）。

全局安装 n8n-node#

您可以通过 npm 全局安装 n8n-node：

npm install --global @n8n/node-cli

验证命令访问权限，请输入：

n8n-node --version

命令概览#

n8n-node 工具提供以下命令：

new#

new 命令为新建节点创建文件系统结构和元数据。该命令初始化的结构与不安装运行 n8n-node 中所述完全一致。

调用此命令时，它会交互式提示输入项目详细信息以定制初始代码。您需要提供项目名称、选择节点类型，并选取最符合需求的起始模板。n8n-node 工具将创建项目文件结构，并可选择安装初始项目依赖项。

在新建节点章节中深入了解如何使用 new 命令。

build#

build 命令会编译节点并复制所有必需资源。

在构建节点章节中深入了解如何使用 build 命令。

dev#

dev 命令将运行包含您节点的 n8n 环境。该命令会监控项目目录，并在检测到变更时自动重建实时预览。

在n8n 中测试节点章节中深入了解如何使用 dev 命令。

lint#

lint 命令会检查当前目录中节点的代码。可选用 --fix 选项尝试自动修复发现的问题。

在代码检查章节中深入了解如何使用 lint 命令。

release#

release 命令将您的社区节点包发布到 npm。该命令使用 release-it 在发布到 npm 前执行清理、检查并重新构建包的操作。

在发布节点章节中深入了解如何使用 release 命令。

创建新节点#

要使用 n8n-node 创建新节点，请调用 n8n-node new。您可以选择完全交互式调用此命令，或在命令行中提供详细信息。

不安装创建新节点

您还可以选择直接使用包管理器配合 @n8n/create-node 初始化工具，无需安装 n8n-node 即可创建项目。

在以下命令中，将 n8n-node new 替换为 npm create @n8n/node@latest。使用此方式时，必须在包含任何选项（如 --template）前添加双破折号（--）。例如：

npm create @n8n/node@latest n8n-nodes-mynode -- --template declarative/custom

该命令将提示您输入节点的所有缺失信息，随后生成项目结构以便您快速开始。默认情况下，它会继续安装初始项目依赖项（您可以通过传递 --skip-install 参数来禁用此功能）。

交互式设置节点详情#

当不带参数调用时，n8n-node new 会以交互方式提示您输入新节点的详细信息：

n8n-node new

这将启动一个交互式提示界面，供您定义项目的详细信息：

• 节点名称：您的节点名称。这将影响项目目录名称、包名称以及n8n节点本身的命名。名称必须采用以下格式之一：
  • n8n-nodes-<您的节点名称>
  • @<您的组织>/n8n-nodes-<您的节点名称>
• 构建节点类型：您要构建的节点类型：
  • HTTP API：采用低代码声明式节点结构，专为加速n8n Cloud审核流程设计
  • 其他：具备完全灵活性的编程式节点
• 选择模板：使用HTTP API时，可选择起始模板：
  • GitHub Issues API：包含多操作项与凭据的演示节点，帮助熟悉节点结构与规范
  • 从零开始：空白模板，将通过后续提示引导完成自定义设置

选择HTTP API > 从零开始时，n8n-node将询问以下内容：

• API基础URL：计划集成的API根地址
• API认证类型：节点应提供的认证方式：
  • API密钥：通过请求头、查询参数或请求体发送密钥
  • Bearer令牌：通过Authorization请求头发送令牌（Authorization: Bearer <令牌>）
  • OAuth2：使用OAuth 2.0流程获取用户或应用访问令牌
  • 基础认证：通过Authorization请求头发送Base64编码的用户名与密码
  • 自定义：创建专属凭据逻辑，生成可按需定制的空凭据类
  • 无认证：无需认证，不为节点创建凭据类

完成选择后，n8n-node将在当前目录中为您的节点创建新项目目录。默认情况下会自动安装初始项目依赖项（可通过--skip-install参数禁用此功能）。

通过命令行提供节点详情#

您可以通过命令行直接提供部分节点详情以避免交互提示。

可将节点名称作为参数直接传入：

n8n-node new n8n-nodes-myproject

节点名称格式

节点名称必须采用以下格式之一：

• @<YOUR_ORG>/n8n-nodes-<YOUR_NODE_NAME>
• n8n-nodes-<YOUR_NODE_NAME>

若已提前确定要使用的模板，也可通过 --template 参数传递对应值：

n8n-node new --template declarative/custom

模板必须是以下选项之一：

• declarative/github-issues：包含多个操作和凭证的演示节点，可帮助您熟悉节点结构和规范。
• declarative/custom：空白模板，将通过进一步提示引导您完成自定义设置。
• programmatic/example：具有完全灵活性的编程风格节点。

构建节点#

您可以通过在项目根目录下运行 build 命令来构建节点：

n8n-node build

n8n-node 将编译您的 TypeScript 文件并打包其他项目资源。您也可以通过包管理器调用 build 脚本，例如使用 npm 时效果相同：

npm run build

代码规范检查你的节点#

n8n-node 工具还会自动为你的项目创建一个 lint 脚本。你可以使用包管理器运行该脚本。例如：

n8n-node lint

您也可以通过包管理器的脚本运行器执行：

npm run lint

如果包含 --fix 选项（也可通过 npm run lint:fix 调用），n8n-node 将尝试修复其识别出的问题：

n8n-node lint --fix

在n8n中测试节点#

要在n8n中测试您的节点，请在项目根目录下运行 dev 命令：

n8n-node dev

与 build 命令类似，您也可以通过包管理器运行此命令。例如：

npm run dev

n8n-node 将编译您的项目，然后通过 npm 启动一个本地 n8n 实例，并加载您的节点。

访问 localhost:5678 登录到您的 n8n 实例。如果打开一个工作流，您的节点将显示在节点面板中：

在此之后，您可以将其添加到工作流中，并在开发过程中测试节点的功能。

发布您的节点#

要发布您的节点，请在项目目录中运行 release 命令。该命令使用 release-it 来构建并发布您的节点。

登录 npm

要使用 release 命令，您必须通过 npm login 命令登录 npm。否则，n8n-node 将无权发布您的项目文件。

n8n-node release

要使用 npm 运行，请输入：

npm run release

当您运行 release 命令时，n8n-node 将执行以下操作：

• 构建节点
• 对文件进行代码规范检查
• 更新更新日志
• 创建 Git 标签
• 创建 GitHub 发布版本
• 将软件包发布到 npm