n8n 中文文档

使用n8n节点工具

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

使用n8n-node,您可以创建符合已验证社区节点指南的节点。

获取n8n节点

运行 n8n-node 而不安装

您可以通过使用包管理器使用 @n8n/create-node 初始化器 直接创建 n8n-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 命令为新节点创建文件系统结构和元数据。此命令初始化与不安装运行 n8n-node中概述的相同结构。

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

在创建新节点部分中了解更多关于如何使用 new 命令的信息。

构建

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

在构建节点部分中了解更多关于如何使用 build 命令的信息。

开发

dev 命令使用您的节点运行 n8n。它监控您的项目目录,并在检测到更改时自动重建实时预览。

在n8n 中测试节点部分中了解更多关于如何使用 dev 命令的信息。

棉绒

lint 命令检查当前目录中节点的代码。您可以选择使用 --fix 选项来尝试自动修复它识别的任何问题。

在检查节点部分中了解更多关于如何使用 lint 命令的信息。

发布

release 命令将您的社区节点包发布到 npm。它使用 release-it 在发布到 npm 之前清理、检查和干净地构建您的包。

在发布节点部分中了解更多关于如何使用 release 命令的信息。

创建新节点

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

提示

Create new node without installing 创建新节点而不安装

您可以选择直接创建 n8n-node 项目,而无需通过包管理器使用 @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-<YOUR_NODE_NAME>
    • @<YOUR_ORG>/n8n-nodes-<YOUR_NODE_NAME>
  • What kind of node are you building? 您正在构建哪种节点? 选择要使用的节点构建样式:
    • HTTP API:一种低代码的声明式节点结构,旨在更快获得 n8n Cloud 的批准。
    • Other 其他:具有充分灵活性的编程式节点。触发器节点应选择此项,因为声明式样式不支持触发器。若要向已有声明式节点的包中添加触发器节点,请在同一个包中使用编程式样式编写该触发器节点。
  • What template do you want to use? 您想使用哪个模板? 使用 HTTP API 时,可选择以下起始模板:
    • GitHub Issues API:包含多个操作和凭据的演示节点,可帮助你熟悉节点结构和约定。
    • Start from scratch 从头开始:空白模板,将通过更多提示引导你完成自定义设置。

选择 HTTP API > 从头开始时,n8n-node 将询问您以下内容:

  • API 的基础 URL 是什么? 您计划集成的 API 的根 URL。
  • 您的 API 使用什么类型的身份验证? 您的节点应提供的身份验证:
    • API Key:使用标头、查询参数或请求体发送密钥。
    • Bearer Token:使用 Authorization 标头发送令牌(Authorization: Bearer <token>)。
    • OAuth2:使用 OAuth 2.0 流程代表用户或应用程序获取访问令牌。
    • Basic Auth:通过 Authorization 标头发送 base64 编码的用户名和密码。
    • Custom 自定义:创建您自己的凭据逻辑。这将创建一个空的凭据类,您可以根据需要进行自定义。
    • None 无:不需要身份验证。不要为节点创建凭据类。

一旦您做出选择,n8n-node 将在当前目录中为您的节点创建一个新项目目录。默认情况下,它还将安装初始项目依赖项(您可以通过传递 --skip-install 标志来禁用此功能)。

在命令行上提供节点详细信息

您可以在命令行上提供一些节点详细信息以避免提示。

您可以将要用于节点的名称作为参数包含:

n8n-node new n8n-nodes-myproject

提示

Node name format 节点名称格式

节点名称必须使用以下格式之一:

  • @<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 会编译项目,然后启动一个已加载该节点的本地 n8n 实例。从 n8n 3.0 起,该实例会在容器中启动,因此需要安装 Docker 或 Podman。如果不希望该命令启动实例,请使用 n8n-node dev --external-n8n 指向你自行运行、并以 N8N_DEV_RELOAD=true 启动的 n8n 实例。采用这种方式时不需要 Docker 或 Podman。

访问您的 localhost:5678 以登录到您的 n8n 实例。如果您打开工作流,您的节点将出现在节点面板中:

工作流编辑器中的 Trigger 搜索面板,结果中列出匹配节点

从那里,您可以将其添加到工作流中,并在开发过程中测试节点的功能。

释放您的节点

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

提示

Log in to npm 登录 npm

要使用 release 命令,您必须使用 npm login 命令登录 npm。如果没有这个,n8n-node 将无权发布您的项目文件。

n8n-node release

要使用 npm 运行,请输入:

npm run release

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

  • 构建节点
  • 对您的文件运行 lint 检查
  • 更新变更日志
  • 创建 git 标签
  • 创建 GitHub 发布
  • 将包发布到 npm

相关资源

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