使用环境变量管理社区包#

自 n8n v2.21.0 起可用

在自托管 n8n 中，你可以通过环境变量管理已安装的社区包集合。n8n 会在每次启动时根据列表与当前已安装包进行对账：安装缺失的包、修正版本，并卸载不在列表中的包。这个方法适合为实例预置一组固定的包，例如通过部署流水线进行初始化。

启用后会卸载不在列表中的包

首次以 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true 启动 n8n 时，n8n 会卸载所有未包含在 N8N_COMMUNITY_PACKAGES 中、但当前已经安装的社区包。如果你之前通过 UI 管理这些包，请先检查 Community nodes 社区节点 设置页，并在启用此变量前，把需要保留的包加入 N8N_COMMUNITY_PACKAGES。

配置#

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

变量	类型	默认值	说明
`N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV`	Boolean	`false`	设为 `true` 后，可通过环境变量管理已安装的社区包。启用后，n8n 会在每次启动时根据 `N8N_COMMUNITY_PACKAGES` 对已安装包进行对账：安装缺失的包、修正版本，并且卸载所有未出现在列表中的当前已安装包。Community nodes 社区节点设置页会变为只读，启用期间无法在 UI 中安装、更新或卸载包。
`N8N_COMMUNITY_PACKAGES`	JSON string	-	要安装的社区包 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 社区节点 设置页会变为只读：你无法通过 UI 安装、更新或卸载包。

每个包的字段#

字段	类型	必填	说明
`name`	string	是	npm 包名。你可以把版本直接写成 `<package-name>@<version>`。如果这样写了，就不要再把 `version` 字段设置为不同的值，否则 n8n 会拒绝冲突版本。
`version`	string	否	版本说明符。如果省略，n8n 会先去 vetted-packages registry 查找该包并使用那里定义的版本；如果该包未被验证，n8n 会安装 npm 最终解析出的版本，并且不会在重启之间对版本进行对账。
`checksum`	string	否	已解析 tarball 的 SHA-512 校验和（`sha512-...`）。设置该字段时必须同时设置 `version`。如果可能，n8n 会自动从 vetted registry 解析出校验和。

包含这三个字段的示例：

[
  { "name": "n8n-nodes-foo", "version": "1.2.3" },
  { "name": "[email protected]" },
  { "name": "n8n-nodes-baz", "version": "2.0.0", "checksum": "sha512-..." }
]

未验证包需要 checksum

如果某个包不在 vetted-packages registry 中，并且 N8N_UNVERIFIED_PACKAGES_ENABLED 为 false，n8n 将无法启动。你需要为该包固定一个 checksum，或者将 N8N_UNVERIFIED_PACKAGES_ENABLED=true，或者改用已验证的包。

关于支持的环境变量设置方式，请参阅配置方式。

管理包#

若要新增、移除、升级或降级某个包，请编辑 N8N_COMMUNITY_PACKAGES 并重启 n8n。n8n 会在下次启动时按新列表重新对账。

版本中的破坏性变更

节点开发者可能会在新版本中引入破坏性变更，也就是会破坏旧功能的更新。调整版本时请谨慎。如果新版本出现问题，请把 version 改回旧值并重启 n8n 进行回退。