导入 package
提示
Preview status 预览状态
n8n packages 处于 Preview 阶段。导入选项在未来版本中可能会发生变化。
导入操作会读取一个 n8n package,即 .n8np 归档,并将其中的内容写入目标实例。n8n 会先检查整个 package:如果存在任何阻止导入的问题,则不会写入内容,并会一次性返回所有问题。详情请参阅导入工作原理。
使用 n8n CLI:
n8n-cli package import --file=triage.n8np --project-id=<target-project-id>
或者直接调用端点。归档放在名为 package 的 multipart 字段中,每个选项都是独立的文本字段:
curl -X POST 'https://n8n.example.com/api/v1/n8n-packages/import' \
-H "X-N8N-API-KEY: <your-api-key>" \
-F '[email protected]' \
-F 'conflictPolicy=new-version' \
-F 'projectId=<target-project-id>'
有关完整的请求和响应模式,请参阅端点参考中的 N8nPackage 部分。
提示
如果直接调用端点而不是使用 CLI,请求必须为 multipart/form-data。任何其他 content type 都会返回 415。conflictPolicy 是必填字段,但 CLI 会替你提供。
n8n 会将空值视为省略并使用默认值。例外是 conflictPolicy:其空值会以 400 被拒绝。
内容的落点
对于工作流或文件夹 package,可以选择目标位置:
| Flag | 说明 |
|---|---|
--file |
.n8np 文件的路径。必填。没有短别名,因为 -f 代表 --format。 |
--project-id, -p |
目标项目 ID。默认为个人项目。别名:--project。 |
--folder-id |
项目内的目标文件夹 ID。默认为项目根目录。别名:--folder。 |
警告
对于项目 package,--project-id 和 --folder-id 会被忽略且不发出警告。项目 package 自带项目,每个项目的内容都会进入该项目的根目录。使用 --project-conflict-policy 控制项目已存在时的行为。
提示
本页始终以 kebab-case 显示标志。n8n-cli package import --help 会输出等效的 camelCase 名称(--projectId、--conflictPolicy、--tagConflictPolicy),错误消息也会使用这些名称。两种写法均有效。
不存在 --force 或 --dry-run。
工作流和 agent 选项
| Flag | 值 | 说明 |
|---|---|---|
--conflict-policy |
new-version(默认)、fail、skip |
工作流或 agent 已存在于目标实例时的处理方式。new-version 保存现有工作流的新版本,或更新现有 agent;fail 拒绝整个导入;skip 保持其不变并继续。new-version 还会归档或恢复工作流,使其与 package 一致。 |
--id-policy |
source(默认且唯一值) |
新的工作流或 agent 保留 package 中的 ID。如果实例上任何位置已有不匹配的工作流或 agent 使用了该 ID,n8n 会拒绝导入。已匹配的工作流或 agent 在目标实例上保留其 ID。 |
--publishing-policy |
preserve-published-state(默认)、match-source、publish-all、unpublish-all |
导入的工作流和 agents 最终是否发布。请参阅发布。 |
--missing-node-type-mode |
fail(默认)、import-anyway |
工作流或 agent 的节点 tool 使用目标实例没有的节点类型或节点版本时的处理方式。fail 会在写入任何内容前拒绝导入,并列出每种缺失类型及使用它的工作流和 agents。import-anyway 会导入它们,但绝不会发布。 |
n8n 会根据目标实例上记录的源工作流 ID,将 package 中的工作流与现有工作流匹配;如果没有匹配项,则回退到自身 ID 与 package ID 相同的目标工作流。这使重复提升能够收敛:第二次导入会更新工作流,而不是创建重复项。
发布
n8n 始终先以未发布状态写入导入的工作流,待所有内容都存在后,在导入结束时一次性应用发布策略。
| 值 | 行为 |
|---|---|
preserve-published-state(默认) |
新工作流保持草稿状态。只有当更新的工作流之前已发布,且 package 中的工作流也已发布时,才会重新发布。 |
match-source |
与 package 中工作流的发布状态保持一致。 |
publish-all |
发布所有导入的工作流。需要对目标项目拥有 workflow:publish。 |
unpublish-all |
新工作流保持草稿状态,更新的工作流则取消发布。 |
有两种情况会覆盖该策略。使用占位凭据或不完整凭据的工作流绝不会发布,使用实例没有的节点类型的工作流也不会发布。n8n 会将它们报告为 blocked 并附上原因。归档工作流同样绝不会发布。
Agents 遵循相同的策略;如果某个渠道仍需设置,也会阻止 agent 发布。
发布也可能失败而不导致导入失败,最常见的情况是两个工作流使用相同的 webhook 路径。请参阅发布结果。
文件夹和项目选项
| Flag | 值 | 说明 |
|---|---|---|
--folder-conflict-policy |
merge、fail、overwrite |
package 中的文件夹已存在于目标项目时的处理方式。默认值与 --project-conflict-policy 相同;对于工作流和文件夹 package,默认值为 merge。merge 会复用现有文件夹,将 package 内容合并到其中,并保留现有名称。fail 会拒绝导入。overwrite 还会移除 package 中不包含的内容。请参阅文件夹和项目。 |
--project-conflict-policy |
merge(默认)、fail、overwrite |
仅适用于项目 package。package 中的项目已存在时的处理方式。merge 不更改项目详情,只添加 package 内容。overwrite 还会替换名称、描述和图标,而 package 未携带的内容保持不变。由于 --folder-conflict-policy 默认取此值,overwrite 还会移除 package 中不包含的工作流,除非你设置 --folder-conflict-policy=merge。fail 会拒绝导入。 |
--overwrite-deletion-policy |
archive(默认)、hard-delete |
--folder-conflict-policy=overwrite 移除工作流的方式。archive 会将其归档,以便你恢复。hard-delete 会永久删除该工作流及其执行记录。 |
对于工作流和文件夹 package,--project-conflict-policy 会被忽略。--folder-conflict-policy=overwrite 只适用于项目 package,并且需要与 --project-conflict-policy=overwrite 一起使用。
即使使用 merge,两种文件夹冲突仍会导致导入被拒绝:文件夹 ID 存在于其他项目中;现有文件夹的父级与导入计划放置的位置不同。任何策略都无法解决这两种情况,因为二者都意味着要移动文件夹。
当导入实际创建或移除文件夹,或者 package 是文件夹 package 时,需要支持文件夹功能的许可证。
凭据选项
| Flag | 值 | 说明 |
|---|---|---|
--credential-matching-mode |
id-only(默认)、name-and-type、type-only |
n8n 如何为 package 中的引用查找目标凭据。 |
--credential-missing-mode |
create-stub(默认)、create-with-values、must-preexist |
无法解析引用时的处理方式。create-stub 会在目标项目中创建一个空的占位凭据,工作流可以导入但无法发布。create-with-values 会根据 package 中打包的表达式值创建凭据。must-preexist 会拒绝导入。 |
--credential-conflict-policy |
keep-existing(默认)、overwrite、fail |
引用匹配到现有凭据,但 package 中该凭据的名称或值不同时的处理方式。keep-existing 保持凭据不变。overwrite 将 package 中的名称和表达式值写入该凭据。fail 会拒绝导入。请参阅已有凭据。 |
在所有模式下,n8n 只会考虑你有权读取且目标项目可以使用的凭据,以及全局凭据。无权读取的凭据永远不会成为候选项,即使在 id-only 模式下也是如此;这通常是 ID 相同却未能匹配的原因。
有关排序规则和完整解析顺序,请参阅凭据。
数据表选项
| Flag | 值 | 说明 |
|---|---|---|
--data-table-matching-mode |
by-id(默认且唯一值) |
匹配目标项目中 ID 相同的数据表,绝不会回退到按名称匹配。 |
--data-table-missing-mode |
create(默认)、must-preexist、do-nothing |
被引用的数据表不在目标项目中时的处理方式。create 会根据 package 中的模式创建数据表,保留源 ID,但不包含行。must-preexist 会拒绝导入。do-nothing 会跳过创建。 |
--data-table-schema-conflict-policy |
keep-existing(默认)、fail、overwrite、overwrite-non-destructive |
已匹配数据表的模式与 package 不同时的处理方式。keep-existing 允许目标表包含自己的额外列。fail 对这种情况也会拒绝导入。overwrite 将目标表改为与 package 一致。overwrite-non-destructive 执行相同变更,但移除列或更改列类型时会拒绝导入。 |
使用 keep-existing 和 fail 时,package 中的每一列都必须存在于已匹配的目标表中,并具有相同的名称和类型。缺少列或类型不匹配都会导致导入被拒绝;源端重命名的列也视为缺失。两种策略都不会更改目标表,因此 package 中的列绝不会添加到目标表。
overwrite 会添加、移除、重命名、更改类型和重排列,并重命名表。行和其他列会保留。移除列或更改列类型会删除该列的值,重命名列则保留其值。变更会影响使用该表的所有工作流。
overwrite-non-destructive 执行相同变更,但遇到移除列或更改列类型时会停止导入,不会写入任何内容。目标表中存在但 package 中没有的列会被视为移除。
有关各策略的更多信息,请参阅数据表。
即使使用 --data-table-missing-mode=do-nothing,已匹配的数据表仍会接受模式检查。该选项控制的是缺失情况,而不是比较行为。
变量选项
| Flag | 值 | 说明 |
|---|---|---|
--variable-missing-mode |
create-with-value(默认)、create-stub、must-preexist、do-nothing |
被引用的变量在目标项目和全局作用域中都不存在时的处理方式。create-with-value 使用 package 中的值创建变量;如果 package 没有该变量的值,则回退到空变量。create-stub 始终创建空变量。must-preexist 会拒绝导入。do-nothing 仍会导入并报告未解析的名称,因此工作流会在运行时失败。 |
--variable-conflict-policy |
keep-existing(默认)、overwrite、fail |
被引用的变量已解析,但 package 携带不同值时的处理方式。keep-existing 保留目标值。overwrite 替换目标值。fail 拒绝导入。 |
--variable-parent-policy |
project(省略时的行为)、global |
新创建变量的放置位置。项目 package 的布局已作出决定,因此使用该选项会以 400 被拒绝。 |
n8n 按名称而不是 ID 匹配变量,这与 $vars.<name> 的运行时解析方式一致:先查找目标项目,再查找全局作用域。
警告
--variable-conflict-policy=overwrite 会写入变量解析到的作用域。如果名称解析到全局变量,读取该变量的其他项目会看到新值。系统不会发出警告。
创建或覆盖变量需要支持变量功能的许可证和对应的 API key 作用域,并且实例的变量限额还要有剩余空间。如果导入中的所有变量都已经解析,则不会写入任何变量,因此不需要上述条件。
标签选项
| Flag | 值 | 说明 |
|---|---|---|
--tag-missing-mode |
create(默认)、do-nothing |
package 引用的标签不在目标实例上时的处理方式。create 会使用源 ID 和名称创建全局标签。do-nothing 会导入不带这些标签的工作流,并将标签列为已跳过。 |
--tag-conflict-policy |
skip(默认)、fail、rename |
标签发生冲突时的处理方式。skip 会丢弃标签并将其列为已跳过。fail 会拒绝导入。rename 会重命名发生名称漂移的目标标签;发生名称冲突时,则将现有标签迁移到 package 中的 ID,同时保留其名称以及带有该标签的所有内容。 |
标签按源 ID 匹配,而绝不会按名称匹配,因为只有通过稳定的 ID 才能检测到重命名。
冲突有两种。名称漂移表示目标标签具有相同 ID 但名称不同,说明有人在某个实例上重命名了它。名称冲突表示目标上不存在该 ID,但另一个标签已经使用了相同名称;在标签独立创建的成熟实例上,这种情况很常见。
警告
丢弃标签可能会从现有工作流中移除标签。n8n 更新工作流时,package 的标签列表会完全替换目标工作流的标签。被丢弃的标签会先从该列表中过滤掉,因此如果更新一个已有标签的工作流,而其 package 标签全部被丢弃,工作流当前的标签也会被清空。
若要保留现有标签,请使用 --include-tags=false 导出。这样会省略标签列表,而不是发送空列表。
如果目标实例设置了 N8N_WORKFLOW_TAGS_DISABLED=true,所有标签处理都会静默跳过,且绝不会导致导入失败。
Bindings 绑定
Bindings 会将 package 中的实体映射到实例上的特定实体,从而跳过匹配规则。请传入以实体类型为键的 JSON 对象。目前只接受 credentials:
n8n-cli package import --file=triage.n8np \
--bindings='{"credentials":{"crLin44":"crProd8"}}'
这会将 package 中的 crLin44 凭据映射到目标上的 crProd8,因此每个使用 crLin44 的工作流都会改用 crProd8。n8n 会在运行 --credential-matching-mode 前应用 bindings,同时仍会检查类型是否匹配:绑定到错误类型的凭据会导致导入被拒绝。
n8n 会以 400 拒绝 credentials 以外的任何键,而不是将其忽略。
无法解析的已绑定凭据始终会导致导入被拒绝,即使使用默认的 create-stub 也是如此。只有未绑定的引用才会获得占位凭据。
n8n 会在响应中返回所使用的 bindings。保存 credentials 映射,并在后续导入时以 --bindings='{"credentials":{...}}' 传回,以保持映射稳定。响应还包含一个仅供参考的 workflows 映射;将其传回会以 400 被拒绝。
从项目 package 导入选定内容
import-selection 会从 package 的某个项目中导入选定的工作流,并可在同一次调用中从目标项目移除工作流。它只接受项目 package,即使用 --project-id 导出得到的那种 package,并会拒绝包含 agents 的 package。
# Import two workflows from the project
n8n-cli package import-selection --file=team-ligo.n8np \
--selected-project-id=prTeam9 \
--selected-workflow-ids=wf7Kq2,wf9Zx1
# Import one workflow and remove another
n8n-cli package import-selection --file=team-ligo.n8np \
--selected-project-id=prTeam9 \
--selected-workflow-ids=wf7Kq2 \
--deleted-workflow-ids=wfOld01
或者以 multipart 表单调用 POST /api/v1/n8n-packages/import-selection,并将归档放在 package 字段中。它只接受下表标志对应的字段,其他 /import 字段会以 400 被拒绝。请以文本字段中的 JSON 数组形式发送 selectedWorkflowIds 和 deletedWorkflowIds,例如 ["wf7Kq2","wf9Zx1"]。
项目 package 可以包含多个项目,因此 --selected-project-id 用于指定从哪个项目获取工作流。n8n 会将它们写入目标实例上 ID 相同的项目;如果该项目不存在,则会创建它。不在任一列表中的工作流以及其他项目都保持不变。
| Flag | 说明 |
|---|---|
--selected-project-id |
要从中获取工作流的 package 项目。必填。 |
--selected-workflow-ids |
要导入的 package 中工作流 ID。可用逗号分隔,或重复使用该标志。 |
--deleted-workflow-ids |
要从目标项目中移除的工作流 ID。n8n 会忽略不在该项目中的 ID。 |
--conflict-policy |
new-version(默认)、fail 或 skip。行为与完整导入相同。 |
--overwrite-deletion-policy |
archive(默认)或 hard-delete。n8n 移除 --deleted-workflow-ids 中工作流的方式。 |
其他选项使用固定值:
- 文件夹: n8n 只创建或合并包含选定工作流的文件夹及其上级文件夹。其他文件夹保持不变。
- 凭据和变量: 它们必须已存在于目标实例上(凭据需具有相同 ID),并且 n8n 不会更改它们。
- 数据表: n8n 按 ID 匹配数据表,并创建缺失的数据表。任何模式差异都会导致导入被拒绝。
- 标签: n8n 会创建缺失的标签,并跳过发生冲突的标签。
- 发布: n8n 遵循
match-source。
响应的结构与完整导入相同,被移除的工作流列在 removedWorkflows 中。
所需作用域请参阅限制与权限。
导入响应
导入成功会返回 200,并附上已执行操作的摘要:
{
"package": {
"sourceN8nVersion": "2.34.0",
"sourceId": "f9e1e962bba26edf357042c12f367dab17f4c63ec368e1f39cbf7ce43c8b9f8b"
},
"agents": [],
"counts": { "agents": { "created": 0, "updated": 0, "skipped": 0 } },
"workflows": [
{ "sourceWorkflowId": "wf9Zx1", "localId": "wf9Zx1", "name": "Send email",
"projectId": "prProd4", "parentFolderId": null,
"activeVersionId": null, "isArchived": false, "publishing": { "state": "unchanged" }, "status": "created" },
{ "sourceWorkflowId": "wf7Kq2", "localId": "wf7Kq2", "name": "Triage inbound",
"projectId": "prProd4", "parentFolderId": null,
"activeVersionId": null, "isArchived": false, "publishing": { "state": "unchanged" }, "status": "created" }
],
"removedWorkflows": [],
"removedFolders": [],
"folders": [],
"projects": [],
"bindings": {
"agents": {},
"workflows": { "wf7Kq2": "wf7Kq2", "wf9Zx1": "wf9Zx1" },
"credentials": { "crLin44": "crLin44" }
},
"credentials": { "matched": ["crLin44"], "stubbed": [], "seeded": [], "incomplete": [], "updated": [] },
"dataTables": { "matched": 0, "created": 1, "updated": 0 },
"variables": { "matched": [], "missing": [], "created": ["slackChannelId"], "stubbed": [], "updated": [] },
"tags": { "matched": [], "created": ["prod"], "renamed": [], "reconciled": [], "skipped": [] }
}
| Key | 包含内容 |
|---|---|
package |
从 manifest 复制的源实例 n8n 版本和实例 ID |
agents |
每个 agent 一行。对于不含 agents 的 package,此项为空。 |
counts |
created、updated 和 skipped 的 agents 数量 |
workflows |
每个工作流一行,包含值为 created、updated 或 skipped 的 status、是否已归档,以及 publishing 结果 |
removedWorkflows |
导入通过 --folder-conflict-policy=overwrite 或 --deleted-workflow-ids 移除的工作流,每项都带有值为 archived 或 deleted 的 deletion。n8n 暂时无法完成的 hard-delete 会报告为 archived |
removedFolders |
--folder-conflict-policy=overwrite 移除的文件夹 |
folders |
每个文件夹一行,status 为 created 或 skipped |
projects |
每个项目一行,status 为 created、updated 或 skipped。对于工作流和文件夹 package,此项为空 |
bindings |
工作流、agents 和凭据从源 ID 到目标 ID 的映射。只有 credentials 映射可以在后续导入时传回 |
credentials |
源凭据 ID,分为 matched、stubbed、seeded、incomplete 和 updated |
dataTables |
matched、created 和 updated 数据表的数量。updated 统计通过 overwrite 或 overwrite-non-destructive 更改的表 |
variables |
变量名称,分为 matched、missing、created、stubbed 和 updated。绝不会显示值 |
tags |
标签名称,分为 matched、created、renamed、reconciled 和 skipped |
工作流的 localId 是它在目标实例上的 ID:新工作流为 package 中的 ID,工作流被更新或跳过时则为现有工作流的 ID。
示例中的两个工作流都是新的,默认的 preserve-published-state 不会发布新工作流,因此两者都报告为 unchanged。要让新工作流以已发布状态到达,请使用 --publishing-policy=publish-all;如果工作流在 package 中标记为 published,也可以使用 match-source。
publishing.state 为 published、unpublished、unchanged、blocked 或 failed 之一。各状态的含义请参阅发布结果。
错误
导入被拒绝时会返回发现的所有问题,而不仅是第一个:
{
"message": "Import blocked: 2 issue(s) must be resolved before the package can be imported.",
"issues": [
{ "type": "missing-node-type", "nodeType": "@acme/cool-node", "typeVersion": 3,
"usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
{ "type": "credential-unresolved", "kind": "not_found", "sourceId": "crLin44",
"usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
]
}
不会写入任何内容。CLI 会以非零状态退出并输出问题列表。
| 状态 | 含义 |
|---|---|
400 |
请求或 package 格式错误;也可能是在项目 package 上使用 --variable-parent-policy,或 --bindings 值无效 |
403 |
缺少 API key 作用域、无权访问目标项目,或许可证不支持文件夹、变量或团队项目 |
404 |
传入的项目 ID 不存在,或没有个人项目 |
409 |
导入因冲突而被拒绝 |
413 |
上传内容超过实例允许的大小 |
415 |
请求不是 multipart/form-data |
422 |
导入因其他原因被拒绝,例如凭据未解析或缺少节点类型 |
有关导入可能被拒绝的完整原因列表及其返回状态,请参阅导入为何被拒绝。
事件
每次导入都会在日志流和遥测路径上发出事件,以便审计进入实例的内容。
| 事件 | 发出时机 |
|---|---|
n8n.audit.n8n-package.import.success |
导入成功 |
n8n.audit.n8n-package.import.failed |
导入失败 |
成功事件包含用户、内容进入的项目和文件夹、写入的工作流和 agents、导入使用的所有选项、package 中的源实例 ID 和格式版本,以及分为 matched、created 和 updated 的凭据 ID。已跳过的工作流和 agents 不会包含在内。即使 package 包含多个项目,也只会发出一个事件。
失败事件包含用户、值为 access-denied、entity-not-found、blocked 或 validation 的 reason;如果导入进行到足以解析目标项目和文件夹的阶段,也会包含二者。事件不包含工作流 ID,因为许多失败发生在 n8n 读取 package 之前。
被拒绝的导入不会发出成功事件。日志流事件包含 ID,但不包含数量;遥测事件包含数量,但不包含 ID。
后续阅读
- 导入工作原理:了解 n8n 写入内容的顺序以及解析每种实体类型的方式。
- 导出 package:了解决定 package 初始形态的选项。
- 限制与权限:了解上传上限和完整作用域矩阵。