跳到主要内容

通过环境变量管理社区软件包

信息

功能可用范围

从 n8n 2.21.0 起，可以通过环境变量管理社区软件包。

在自托管 n8n 中，可以通过环境变量管理已安装的社区软件包。每次启动时，n8n 都会将已安装软件包与列表进行核对，安装缺失的软件包、调整版本，并卸载不在列表中的软件包。可以用此方式为实例初始化固定的一组软件包，例如通过部署流水线进行配置。

注意

启用此功能会卸载不在列表中的软件包

首次使用 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true 启动 n8n 时，n8n 会卸载当前已安装但未包含在 N8N_COMMUNITY_PACKAGES 中的所有社区软件包。如果已经通过界面管理软件包，请先检查 Community nodes（社区节点）设置页，并将希望保留的软件包加入 N8N_COMMUNITY_PACKAGES，再启用此变量。

配置 ​

在 n8n 实例上设置以下环境变量，然后重启：

变量类型默认值说明
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENVBooleanfalse设为 true，通过环境变量管理已安装的社区节点包。当值为 true 时，n8n 会在每次启动时根据 N8N_COMMUNITY_PACKAGES 校正已安装的包：安装缺失的包、纠正版本，并卸载当前已安装但不在列表中的所有包。**Community nodes（社区节点）**设置页会变为只读，启用期间无法通过界面安装、更新或卸载包。
N8N_COMMUNITY_PACKAGESJSON 字符串-要安装的社区节点包的 JSON 数组。每项是一个对象，包含必需的 name 字段，以及可选的 version 和 checksum 字段。也可以通过 <package-name>@<version> 形式，将版本写在名称中。完整字段参考请参阅通过环境变量安装。
信息

必须启用社区软件包

N8N_COMMUNITY_PACKAGES_ENABLED 必须为 true（默认值）。如果在实例级别禁用了社区软件包，n8n 会忽略 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV，并在启动时记录警告。

例如：

export N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true
export N8N_COMMUNITY_PACKAGES='[{"name":"n8n-nodes-foo","version":"1.2.3"}]'

当 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV 为 true 时，Community nodes（社区节点）设置页为只读，无法通过界面安装、更新或卸载软件包。

每个软件包的字段 ​

字段类型必填说明
namestring是npm 软件包名称。可以使用 <package-name>@<version> 在名称中直接指定版本；此时不要再将 version 字段设为其他版本，n8n 会拒绝冲突的版本设置。
versionstring否版本说明符。省略时，n8n 会在审核通过的软件包注册表（vetted-packages registry）中查找并使用对应版本；如果软件包未经审核，则安装 npm 解析出的版本，并且不会在后续重启时核对和调整版本。
checksumstring否已解析的软件包压缩文件的 SHA-512 校验和（sha512-...）。要求设置 version。n8n 会在可能时自动从审核通过的注册表中获取校验和。

包含全部三个字段的示例：

[
  { "name": "n8n-nodes-foo", "version": "1.2.3" },
  { "name": "n8n-nodes-bar@0.5.0" },
  { "name": "n8n-nodes-baz", "version": "2.0.0", "checksum": "sha512-..." }
]
注意

未经验证的软件包需要校验和

如果软件包不在审核通过的软件包注册表中，且 N8N_UNVERIFIED_PACKAGES_ENABLED 为 false，n8n 将无法启动。请为软件包固定一个 checksum、设置 N8N_UNVERIFIED_PACKAGES_ENABLED=true，或选择已经审核通过的软件包。

支持哪些环境变量设置方式，请参阅配置方式。

管理软件包 ​

要添加、移除、升级或降级软件包，请编辑 N8N_COMMUNITY_PACKAGES 并重启 n8n。n8n 会在下次启动时按新列表调整软件包。

注意

版本中的不兼容变更

节点开发者可能在新版本中引入不兼容变更，即破坏原有功能的更新。切换版本时请谨慎。如果新版本导致问题，请将 version 设回原值并重启 n8n，以回滚到之前的版本。

本文为社区中文翻译。查看对应英文原文