Skip to content

节点文件结构#

¥Node file structure

遵循节点结构中的最佳实践和标准，可以使节点更易于维护。如果其他人需要使用代码，这将很有帮助。

¥Following best practices and standards in your node structure makes your node easier to maintain. It's helpful if other people need to work with the code.

节点的文件和目录结构取决于：

¥The file and directory structure of your node depends on:

  • 你的节点复杂度。

¥Your node's complexity.

  • 是否启用节点版本控制。

¥Whether you use node versioning.

  • npm 包中包含多少个节点？

¥How many nodes you include in the npm package.

n8n 建议使用 n8n-node 工具 创建预期的节点文件结构。你可以根据需要自定义生成的脚手架，以满足更复杂的需求。

¥n8n recommends using the n8n-node tool to create the expected node file structure. You can customize the generated scaffolding as required to meet more complex needs.

必填文件和目录#

¥Required files and directories

你的节点必须包含：

¥Your node must include:

  • 项目根目录下的一个 package.json 文件。每个 npm 模块都需要这样做。

¥A package.json file at the root of the project. Every npm module requires this.

  • 一个 nodes 目录，包含你的节点代码：

¥A nodes directory, containing the code for your node:

  • 此目录必须包含 基础文件，格式为 <node-name>.node.ts。例如，MyNode.node.ts。

    ¥This directory must contain the base file, in the format <node-name>.node.ts. For example, MyNode.node.ts.

  • n8n 建议你包含一个 代码库文件 文件，其中包含节点的元数据。代码库文件名必须与节点基本文件名匹配。例如，给定一个名为 MyNode.node.ts 的节点基础文件，其代码库名称为 MyNode.node.json。

    ¥n8n recommends including a codex file, containing metadata for your node. The codex filename must match the node base filename. For example, given a node base file named MyNode.node.ts, the codex name is MyNode.node.json.

  • nodes 目录可以包含其他文件和子目录，包括版本目录以及拆分到多个文件中的节点代码，以创建模块化结构。

    ¥The nodes directory can contain other files and subdirectories, including directories for versions, and node code split across more than one file to create a modular structure.

  • 一个 credentials 目录，包含你的凭据代码。此代码位于单个 凭据文件 中。文件名格式为 <node-name>.credentials.ts。例如，MyNode.credentials.ts。

¥A credentials directory, containing your credentials code. This code lives in a single credentials file. The filename format is <node-name>.credentials.ts. For example, MyNode.credentials.ts.

模块化结构#

¥Modular structure

你可以选择将节点的所有功能放在一个文件中，或者将其拆分为一个基础文件和其他模块，然后由基础文件导入这些模块。除非你的节点非常简单，否则最佳实践是将其拆分。

¥You can choose whether to place all your node's functionality in one file, or split it out into a base file and other modules, which the base file then imports. Unless your node is very simple, it's a best practice to split it out.

基本模式是将操作分离。请参阅 HttpBin 入门节点，查看相关示例。

¥A basic pattern is to separate out operations. Refer to the HttpBin starter node for an example of this.

对于更复杂的节点，n8n 建议使用目录结构。请参考 Airtable 节点 或 Microsoft Outlook 节点 示例。

¥For more complex nodes, n8n recommends a directory structure. Refer to the Airtable node or Microsoft Outlook node as examples.

  • actions：包含代表资源的子目录的目录。

¥actions: a directory containing sub-directories that represent resources.

  • 每个子目录应包含两种类型的文件：

    ¥Each sub-directory should contain two types of files:

    • 包含资源描述的索引文件（名称为 <resourceName>.resource.ts 或 index.ts）。

    ¥An index file with resource description (named either <resourceName>.resource.ts or index.ts)

    • 操作 <operationName>.operation.ts 的文件。这些文件应包含两个导出项：description 是操作和 execute 函数。

    ¥Files for operations <operationName>.operation.ts. These files should have two exports: description of the operation and an execute function.

  • methods：可选的目录动态参数函数。

¥methods: an optional directory dynamic parameters' functions.

  • transport：包含通信实现的目录。

¥transport: a directory containing the communication implementation.

版本控制#

¥Versioning

如果你的节点有多个版本，并且你使用了完整版本控制，则文件结构会更加复杂。每个版本都需要一个目录，以及一个设置默认版本的基础文件。有关使用版本（包括版本类型）的更多信息，请参阅 节点版本控制。

¥If your node has more than one version, and you're using full versioning, this makes the file structure more complex. You need a directory for each version, along with a base file that sets the default version. Refer to Node versioning for more information on working with versions, including types of versioning.

决定数量要包含在包中的节点#

¥Decide how many nodes to include in a package

构建节点时有两种可能的设置：

¥There are two possible setups when building a node:

  • 一个节点位于一个 npm 包中。

¥One node in one npm package.

  • 单个 npm 包中包含多个节点。

¥More than one node in a single npm package.

n8n 支持两种方法。如果你包含多个节点，则每个节点都应该在 nodes 目录中拥有自己的目录。

¥n8n supports both approaches. If you include more than one node, each node should have its own directory in the nodes directory.

程序化节点的最佳实践示例#

¥A best-practice example for programmatic nodes

n8n 内置的 Airtable 节点 实现了模块化结构和版本控制，遵循推荐模式。

¥n8n's built-in Airtable node implements a modular structure and versioning, following recommended patterns.