Skip to content

节点版本控制(Node versioning)#

n8n 支持节点版本控制。你可以通过引入新版本对现有节点进行修改，而不会破坏现有的行为。

🌐 n8n supports node versioning. You can make changes to existing nodes without breaking the existing behavior by introducing a new version.

请注意 n8n 如何决定加载哪个节点版本：

🌐 Be aware of how n8n decides which node version to load:

  • 如果用户使用版本 1 构建并保存了工作流，即使你创建并发布了节点的版本 2，n8n 仍会在该工作流中继续使用版本 1。
  • 当用户创建新工作流并浏览节点时，n8n 始终加载节点的最新版本。

版本类型受节点风格限制

如果你使用声明式风格构建节点，就无法使用完整版本控制。

轻量级版本控制(Light versioning)#

此功能适用于所有节点类型。

🌐 This is available for all node types.

一个节点可以包含多个版本，从而在不重复代码的情况下进行小版本增量。要使用此功能：

🌐 One node can contain more than one version, allowing small version increments without code duplication. To use this feature:

  1. 将主要的 version 参数改为数组，并添加你的版本号，包括你现有的版本。
  2. 然后，你可以在任何对象的 displayOptions 中通过 @version 访问版本参数（用于控制 n8n 显示对象的版本）。你也可以使用 const nodeVersion = this.getNode().typeVersion; 从函数中查询版本。

例如，假设你想为 Declarative node tutorial 中的 NasaPics 节点添加版本控制，那么可以配置一个资源，使 n8n 只在该节点的第 2 版中显示它。在你的基础 NasaPics.node.ts 文件中：

🌐 As an example, say you want to add versioning to the NasaPics node from the Declarative node tutorial, then configure a resource so that n8n only displays it in version 2 of the node. In your base NasaPics.node.ts file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
    displayName: 'NASA Pics',
    name: 'NasaPics',
    icon: 'file:nasapics.svg',
    // List the available versions
    version: [1,2,3],
    // More basic parameters here
    properties: [
        // Add a resource that's only displayed for version2
        {
            displayName: 'Resource name',
            // More resource parameters
            displayOptions: {
                show: {
                    '@version': 2,
                },
            },
        },
    ],
}

基于功能的版本控制(Feature-based versioning)#

功能标志让你可以根据与节点版本相关联的命名功能来控制参数的可见性和执行逻辑。

🌐 Feature flags let you control parameter visibility and execution logic based on named features tied to node versions.

定义特性(Defining features)#

在你的节点类型描述中添加一个 features 对象。每个功能使用 @version 条件来指定哪些版本启用它：

🌐 Add a features object to your node type description. Each feature uses @version conditions to specify which versions enable it:

1
2
3
4
5
6
7
8
9
{
    version: [2, 2.1, 2.2, 2.3, 2.4],
    features: {
        useNewApi: { '@version': [{ _cnd: { gte: 2.2 } }] },
        useLegacyAuth: { '@version': [{ _cnd: { lte: 2.1 } }] },
        useSpecialMode: { '@version': [2] },
    },
    // More basic parameters here
}

可用条件：gte、lte、gt、lt。传递一个纯版本号以匹配特定版本。

🌐 Available conditions: gte, lte, gt, lt. Pass a plain version number to match a specific version.

在 displayOptions 中使用 @feature(Using @feature in displayOptions)#

在 displayOptions 中使用 @feature 根据功能标志控制参数可见性：

🌐 Use @feature in displayOptions to control parameter visibility based on feature flags:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    displayName: 'New API Field',
    name: 'newApiField',
    type: 'string',
    displayOptions: {
        show: {
            '@feature': ['useNewApi'],
        },
    },
}

要在功能未启用时显示参数，请使用条件语法：

🌐 To show a parameter when a feature is not enabled, use the condition syntax:

1
2
3
4
5
displayOptions: {
    show: {
        '@feature': [{ _cnd: { not: 'useNewApi' } }],
    },
}

你可以将 @feature 与其他显示条件结合使用：

🌐 You can combine @feature with other display conditions:

1
2
3
4
5
6
displayOptions: {
    show: {
        resource: ['myResource'],
        '@feature': [{ _cnd: { eq: 'useNewApi' } }],
    },
}

检查代码中的功能(Checking features in code)#

在执行上下文中使用 this.isNodeFeatureEnabled()（例如 IExecuteFunctions 或 IWebhookFunctions）：

🌐 Use this.isNodeFeatureEnabled() in execution contexts (such as IExecuteFunctions or IWebhookFunctions):

1
2
3
4
5
if (this.isNodeFeatureEnabled('useNewApi')) {
    // Process with new API
} else {
    // Process with legacy API
}

完整版本控制(Full versioning)#

声明式节点不支持此功能。

🌐 This isn't available for declarative-style nodes.

例如，请参阅 Mattermost 节点。

🌐 As an example, refer to the Mattermost node.

完整版本控制摘要：

🌐 Full versioning summary:

  • 基础节点文件应该继承 NodeVersionedType 而不是 INodeType。
  • 基础节点文件应包含描述信息，包括 defaultVersion（通常是最新的）、其他基本节点元数据如名称，以及版本列表。它不应包含任何节点功能。
  • n8n 建议在版本文件夹名称中使用 v1、v2 等。