Skip to content

使用 n8n-node 工具#

¥Using the n8n-node tool

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

¥The n8n-node tool is the official CLI for developing community nodes for n8n. You can use it to scaffold out new nodes, build your projects, and run your node as you develop it.

使用 n8n-node，你可以创建符合 已验证社区节点指南 规范的节点。

¥Using n8n-node, you can create nodes that adhere to the guidelines for verified community nodes.

获取 n8n 节点#

¥Get n8n-node

无需安装即可运行 n8n-node#

¥Run n8n-node without installing

你可以使用 @n8n/create-node 初始化程序 和你的包管理器直接创建 n8n-node 项目，无需安装：

¥You can create an n8n-node project directly without installing by using the @n8n/create-node initializer with your package manager:

1
npm create @n8n/node@latest

此设置用于在本地设置初始项目文件（无需在本地安装 n8n-node 并显式运行 new 命令）。之后，你可以通过项目目录中的包管理器脚本运行器运行剩余的 n8n-node 命令（例如，npm run dev）。

¥This sets up the initial project files locally (an alternative to installing n8n-node locally and explicitly running the new command). Afterward, you run the rest of the n8n-node commands through your package manager's script runner inside the project directory (for example, npm run dev).

全局安装 n8n-node#

¥Install n8n-node globally

你可以使用 npm 全局安装 n8n-node：

¥You can install n8n-node globally with npm:

1
npm install --global @n8n/node-cli

通过键入以下命令验证是否可以访问该命令：

¥Verify access to the command by typing:

1
n8n-node --version

命令概览#

¥Command overview

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

¥The n8n-node tool provides the following commands:

new#

new 命令为新节点创建文件系统结构和元数据。此命令初始化与 运行 n8n-node 无需安装 中概述的相同结构。

¥The new command creates the file system structure and metadata for a new node. This command initializes the same structure as outlined in run n8n-node without installing.

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

¥When called, it interactively prompts for details about your project to customize your starting code. You'll provide the project name, choose a node type, and select the starting template that best matches your needs. The n8n-node tool will create your project file structure and optionally install your initial project dependencies.

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

¥Learn more about how to use the new command in the creating a new node section.

build#

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

¥The build command compiles your node and copies all the required assets.

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

¥Learn more about how to use the build command in the building your node section.

dev#

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

¥The dev command runs n8n with your node. It monitors your project directory and automatically rebuilds the live preview when it detects changes.

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

¥Learn more about how to use the dev command in the testing your node in n8n section.

lint#

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

¥The lint command checks the code for the node in the current directory. You can optionally use with the --fix option to attempt to automatically fix any issues it identifies.

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

¥Learn more about how to use the lint command in the lint your node section.

release#

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

¥The release command publishes your community node package to npm. It uses release-it to clean, check and cleanly build your package before publishing it to npm.

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

¥Learn more about how to use the release command in the release your node section.

创建新节点#

¥Creating a new node

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

¥To create a new node with n8n-node, call n8n-node new. You can call this command entirely interactively or provide details on the command line.

Create new node without installing

你可以选择使用包管理器通过 @n8n/create-node 初始化程序 直接创建 n8n-node 项目，而无需安装 n8n-node。

¥You can optionally create an n8n-node project directly without installing n8n-node by using the @n8n/create-node initializer with your package manager.

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

¥In the commands below, substitute n8n-node new with npm create @n8n/node@latest. When using this form, you must add a double dash (--) before including any options (like --template). For example:

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

该命令将提示你输入有关节点的任何缺失信息，然后生成项目结构以帮助你入门。默认情况下，它会继续安装初始项目依赖（你可以通过传递 --skip-install 标志来禁用此功能）。

¥The command will prompt for any missing information about your node and then generate a project structure to get you started. By default, it will follow up by installing the initial project dependencies (you can disable this by passing the --skip-install flag).

交互式设置节点详细信息#

¥Setting node details interactively

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

¥When called without arguments, n8n-node new prompts you for details about your new node interactively:

1
n8n-node new

这将启动一个交互式提示，你可以在其中定义项目的详细信息：

¥This will start an interactive prompt where you can define the details of your project:

  • 你的节点叫什么名字？你的节点的名称。这将影响你的项目目录名称、包名称以及 n8n 节点本身。名称必须使用以下格式之一：

¥What is your node called? The name of your node. This impacts the name of your project directory, package name, and the n8n node itself. The name must use one of the following formats:

  • n8n-nodes-<YOUR_NODE_NAME>

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

  • 你正在构建什么类型的节点？你要构建的 node 类型：

¥What kind of node are you building? The node type you want to build:

  • HTTP API:旨在加快 n8n Cloud 审批速度的低代码声明式节点结构。

    ¥HTTP API: A low-code, declarative node structure that's designed for faster approval for n8n Cloud.

  • 其他：具有完全灵活性的程序化风格节点。

    ¥Other: A programmatic style node with full flexibility.

  • 你想使用什么模板？使用 HTTP API 时，你可以选择要使用的模板：

¥What template do you want to use? When using the HTTP API, you can choose the template to start from:

  • GitHub Issues API：包含多个操作和凭据的演示节点。这可以帮助你熟悉节点结构和约定。

    ¥GitHub Issues API: A demo node that includes multiple operations and credentials. This can help you get familiar with the node structure and conventions.

  • 从头开始：一个空白模板，它将引导你完成自定义设置，并提供一些进一步的提示。

    ¥Start from scratch: A blank template that will guide you through your custom setup with some further prompts.

选择“HTTP API > 从头开始​​”时，n8n-node 将询问你以下信息：

¥When choosing HTTP API > Start from scratch, n8n-node will ask you the following:

  • API 的基本 URL 是什么？你计划集成的 API 的根 URL。

¥What's the base URL of the API? The root URL for the API you plan to integrate with.

  • 你的 API 使用哪种类型的身份验证？你的节点应提供的身份验证：

¥What type of authentication does your API use? The authentication your node should provide:

  • API 密钥：使用请求头、查询参数或请求正文发送密钥

    ¥API Key: Send a secret key using headers, query parameters, or the request body.

  • Bearer 令牌：使用 Authorization 标头 (Authorization: Bearer <token>) 发送令牌。

    ¥Bearer Token: Send a token using the Authorization header (Authorization: Bearer <token>).

  • OAuth2：使用 OAuth 2.0 流程代表用户或应用获取访问令牌。

    ¥OAuth2: Use an OAuth 2.0 flow to get access tokens on behalf of a user or app.

  • 基本身份验证：通过 Authorization 标头发送 base64 编码的用户名和密码。

    ¥Basic Auth: Send the base64-encoded username and password through Authorization headers.

  • 自定义：创建你自己的凭证逻辑。这将创建一个空的凭证类，你可以根据需要进行自定义。

    ¥Custom: Create your own credential logic. This will create an empty credential class that you can customize according to your needs.

  • 无：无需身份验证。请勿为该节点创建凭据类。

    ¥None: No authentication necessary. Don't create a credential class for the node.

完成选择后，n8n-node 将在当前目录中为你的节点创建一个新的项目目录。默认情况下，它还会安装初始项目依赖（你可以通过传递 --skip-install 标志来禁用此功能）。

¥Once you've made your selections, n8n-node will create a new project directory for your node in the current directory. By default, it will also install the initial project dependencies (you can disable this by passing the --skip-install flag).

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

¥Providing node details on the command line

你可以在命令行中提供一些节点详细信息，以避免出现提示。

¥You can provide some of your node details on the command line to avoid prompts.

你可以将节点名称作为参数包含在内：

¥You can include the name you want to use for your node an argument:

1
n8n-node new n8n-nodes-myproject

Node name format

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

¥Node names must use one of the following formats:

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

  • n8n-nodes-<YOUR_NODE_NAME>

如果你事先知道要使用的模板，也可以使用 --template 标志传递该值：

¥If you know the template you want to use ahead of time, you can also pass the value using the --template flag:

1
n8n-node new --template declarative/custom

模板必须是以下之一：

¥The template must be one of the following:

  • declarative/github-issues：包含多个操作和凭据的演示节点。这可以帮助你熟悉节点结构和约定。

¥declarative/github-issues: A demo node that includes multiple operations and credentials. This can help you get familiar with the node structure and conventions.

  • declarative/custom：一个空白模板，它将引导你完成自定义设置，并提供一些进一步的提示。

¥declarative/custom: A blank template that will guide you through your custom setup with some further prompts.

  • programmatic/example：具有完全灵活性的程序化风格节点。

¥programmatic/example: A programmatic style node with full flexibility.

构建节点#

¥Building your node

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

¥You can build your node by running the build command in your project's root directory:

1
n8n-node build

n8n-node 将编译你的 TypeScript 文件并打包你的其他项目资源。你还可以从包管理器调用 build 脚本。例如，如果你使用 npm，其工作方式相同：

¥n8n-node will compile your TypeScript files and bundle your other project assets. You can also call the build script from your package manager. For instance, if you're using npm, this works the same:

1
npm run build

代码检查节点#

¥Lint your node

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

¥The n8n-node tool automatically creates a lint script for your project as well. You can run with your package manager. For example:

1
n8n-node lint

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

¥You can also run through your package manager's script runner:

1
npm run lint

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

¥If you include the --fix option (also callable with npm run lint:fix), n8n-node will attempt to fix the issues that it identifies:

1
n8n-node lint --fix

在 n8n 中测试你的节点#

¥Testing your node in n8n

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

¥To test your node in n8n, you run the dev command in your project's root directory:

1
n8n-node dev

与 build 命令一样，你也可以通过软件包管理器运行此命令。例如：

¥As with the build command, you can also run this through your package manager. For example:

1
npm run dev

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

¥n8n-node will compile your project and then start up a local n8n instance through npm with your node loaded.

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

¥Visit your localhost:5678 to sign in to your n8n instance. If you open a workflow, your node appears in the nodes panel:

node in nodes panel

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

¥From there, you can add it to your workflow and test the node's functionality as you develop.

发布你的节点#

¥Release your node

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

¥To publish your node, run the release command in your project directory. This command uses release-it to build and publish your node.

Log in to npm

要使用 release 命令，你必须使用 npm login 命令登录 npm。如果没有此设置，n8n-node 将无权发布你的项目文件。

¥To use the release command, you must log in to npm using npm login command. Without this, n8n-node won't have authorization to publish your project files.

1
n8n-node release

要使用 npm 运行，请键入：

¥To run with npm, type:

1
npm run release

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

¥When you run the release command, n8n-node will perform the following actions:

  • 构建节点

¥build the node

  • 对文件运行 lint 检查

¥run lint checks against your files

  • 更新变更日志

¥update the changelog

  • 创建 Git 标签

¥create git tags

  • 创建 GitHub 发布

¥create a GitHub release

  • 将包发布到 npm

¥publish the package to npm