导入的工作原理
提示
Preview status 预览状态
n8n packages 处于 Preview 阶段。Import 行为可能会在未来版本中发生变化。
本页说明调用 import 后,n8n 如何处理 n8n package:如何判断能否继续导入,以及如何解析每种 entity。
先检查所有内容,再写入
Import 分两个阶段运行。首先,n8n 会制定计划:读取 package、确定对每个 entity 要执行的操作,并收集所有会阻止 import 的原因。随后,它会连同 license、permission 和 quota 要求一起检查这些原因。只有不存在 blocking issue 时,才会开始写入。
你会一次性获得所有问题。 Import 被拒绝时,会在 issues array 中一并返回所有原因,而不是遇到第一个问题就停止。因此,你可以一次修复整个 pipeline,不必为发现每个新错误而反复运行 import。
被拒绝的 import 不会写入任何内容。 如果 import 被阻止,则不会创建或更改任何 workflow、folder、credential、data table、variable 或 tag。
警告
Import 无法 rollback。n8n 不会用 database transaction 包裹 import,因此「被拒绝的 import 不写入任何内容」这一保证只覆盖可预见的问题,而非所有可能的 failure。如果写入 import 的过程中发生意外,例如 database connection 中断,已经写入的内容会保留在实例上,之后也不会自动清理。预先检查让这种情况很少发生,但无法完全排除。
Import 永远不会删除 project、data table 或 tag。只有在使用 --folder-conflict-policy=overwrite 时,它才会移除 workflow 和 folder;或者在导入选定内容时,移除你在 --deleted-workflow-ids 中指定的 workflow。请参阅 Folders 和 projects。使用 --data-table-schema-conflict-policy=overwrite 时,它可以从 data table 中移除 column。请参阅数据表。
写入顺序
在 project 内,n8n 按固定顺序写入:
tags → folders → credentials → data tables → workflows → variables → publish
Tag 最先写入,因为附加 tag 是写入 workflow 的一部分。Variable 最后写入,因为覆盖 variable 是唯一会更改已有数据的步骤,且此前的步骤都不会读取 variable:$vars 在 runtime 按名称解析,而不是在 import 时解析。
Publish 是最后单独执行的一轮操作,会在 package 中的每个 project 都写入后进行。这是必要的,因为 workflow 调用的所有内容存在之前,workflow 无法发布。
Workflow content 按 manifest 中列出的顺序写入。Publish pass 才会按照 sub-workflow graph 排序,并从 leaf 开始,因为如果 sub-workflow 尚未发布,发布调用它的 workflow 就会失败。Dependency cycle 中的 workflow 最后发布。
对于 project package,n8n 会规划所有 project、检查整个 package、创建 project shell,接着依次写入每个 project 的内容,最后统一发布所有内容。
重写引用
导入 workflow 中的引用必须指向 target instance 上的 entity,而不是 source。n8n 会在处理过程中建立 source ID 到 target ID 的映射,并通过该映射重写四类内容:
- 节点上的 credential ID。
- Execute Workflow、Call n8n Workflow Tool 和 Workflow Retriever 节点上的 sub-workflow ID,但仅限节点从列表选择 workflow,而不是通过 expression 指定时。
- Workflow settings 中的 error workflow。
- Workflow settings 中的 caller allowlist,逐个 element 重写。无法映射的 ID 会保持原样。
有两类内容不会重写。通过 expression 设置的引用会保持不变,因为 n8n 无法知道 expression 的计算结果。Sub-workflow 节点中缓存的 display name 也不会更新,因此重新映射的 sub-workflow 可能会在 editor 中显示旧名称,直到你重新打开节点。
Credentials 凭据
Package 最多只携带 credential 的表达式值,绝不会携带其 secret,因此必须针对 target instance 解析每个 credential reference。n8n 按以下顺序解析:
- 如果为该 credential 提供了显式 binding,则使用该 binding。
- 否则,使用
--credential-matching-mode规则。 - 再否则,由
--credential-missing-mode决定创建空 placeholder、根据 package 中的表达式值创建 credential,还是拒绝 import。
无论采用哪条路径,n8n 都会检查类型。类型错误的 credential 会导致 import 被拒绝,并同时说明节点需要的类型和 credential 的实际类型。显式 binding 也适用此规则。
哪些 credential 可以作为候选项
n8n 只考虑你有权读取、target project 可以使用的 credential,以及 global credential。你无权读取的 credential 在任何模式下都不会成为候选项,包括 id-only。如果 ID 匹配的 credential 未能匹配,通常就是这个原因。
如何选择匹配项
id-only 要么找到 ID,要么找不到。name-and-type 和 type-only 可能得到多个候选项,因此 n8n 会按严格层级选择:
- Target project 拥有的 credential。
- 共享给 target project 的 credential。
- Global credential。
这些是严格层级,而不是评分系统。只要 target project 拥有任意匹配 credential,n8n 就完全不会查看 shared 或 global credential。在胜出的层级中,最近更新的 credential 优先;如果两个 credential 在同一时刻更新,则 ID 较小者优先。
Shared credential 可以作为候选项。跳过它们会破坏常见的 promotion 场景,而且无论如何,执行 import 的用户都必须拥有 credential 的读取权限。
Placeholder credentials 占位凭据
使用默认的 --credential-missing-mode=create-stub 时,n8n 无法解析的引用会在 target project 中变成空 credential,并使用 package 中的 credential 名称。Workflow 会被导入,n8n 会在 credentials.stubbed 中报告该 credential,并返回新的 binding,便于下次复用。
无论 publishing policy 如何,使用 placeholder credential 的 workflow 都不会发布。请先填写 credential,再发布 workflow。
使用 --credential-missing-mode=create-with-values 时,n8n 会改为根据 package 中打包的表达式值创建 credential。package 未携带任何值的 credential 仍会成为空 placeholder。如果 package 确认携带了 source credential 的全部数据,n8n 会在 credentials.seeded 中列出该 credential;否则会在 credentials.incomplete 中列出,使用它的 workflow 在你填写之前不会发布。
即使使用 create-stub,某些 credential 问题仍会拒绝 import,因为 placeholder 无法解决:实例未安装某种 credential type、binding 指向错误类型的 credential,以及为 package 未声明的 credential 提供 binding。
已有 credentials
默认情况下,n8n 永远不会更改已匹配的 credential。使用 --credential-conflict-policy=overwrite 时,它会将 package 中的名称和表达式值写入匹配的 credential,并保留其他所有已存储的值(例如 secret),同时在 credentials.updated 中列出该 credential。使用 fail 时,如果 overwrite 会更改某个 credential,n8n 会拒绝 import。
overwrite 只会更改由 import 写入的 project 所拥有的 credential:即 target project,或 project package 中的每个 project。其他任何匹配的 credential(例如共享给该 project 或由其他 project 拥有的 credential)会按原样使用。Managed credential、按最终用户解析的 credential 以及实例级 credential 永远不会被更改。
使用 overwrite 和 fail 时,你需要拥有更新 import 可能更改的每个匹配 credential 的权限,即使其值相同也是如此,因为 n8n 会比较已存储的值。如果要在没有该权限的情况下复用此类 credential,请使用 keep-existing。当 package 中的值与之匹配时,任何 policy 都不会改动该 credential。
Variables 变量
Variable 始终按名称匹配,而不是按 ID,因为 $vars.<name> 会在 runtime 按名称解析。n8n 会像实际运行 workflow 一样,先查看 target project,再查看 global scope。不存在可携带的 portable ID,因此 package requirement 只记录名称。
Export 时,如果同一名称同时存在于 project 和 global scope 中,则 project value 优先。如果同一名称会在一个 package 内解析成两个不同 variable,export 会被拒绝。
Import 时,无法解析的 variable 由 --variable-missing-mode 处理;可以解析的 variable 由 --variable-conflict-policy 处理。如果无需更改,两项 policy 都不会触碰已解析的 variable,也就是 package 未携带其 value,或 value 已匹配。
写入 variable 需要支持 variables 的 license。创建 variable 还需要 create scope,且实例的 variable limit 必须有剩余容量。覆盖 variable 需要 update scope,但不会占用剩余容量,因为该 variable 已计入限制。限制会统计实例上的所有 variable,包括 global 和 project-scoped variable;如果新 variables 会超出限制,n8n 会在写入任何内容前拒绝 import。
既不创建也不覆盖 variable 的 import 不需要上述任何条件。使用默认的 --variable-conflict-policy=keep-existing 时,只要所有 variable name 都能解析,就属于这种情况。
使用 --variable-conflict-policy=overwrite 时,如果 package 中的多个 project 为它们共同解析到的同一个 variable 保存了不同 value,import 会被拒绝。一个 variable 无法同时承载两个 value,因此 n8n 不会让最后一次写入在没有提示的情况下胜出。
Data tables 数据表
只有 schema 会随 package 传输。Row 在两个方向上都不会移动,因此 import 创建的 table 初始为空。
Table 在 target project 内按 ID 匹配,而不是按名称匹配。新建 table 会保留 source ID。
--data-table-schema-conflict-policy 决定匹配的数据表模式与 package 不同时如何处理:
| 策略 | 行为 |
|---|---|
keep-existing(默认) |
不更改目标表。如果 package 中的数据表列在目标表中缺失或类型不同,则拒绝导入。允许目标表包含自己的额外列 |
fail |
与 keep-existing 相同,但目标表包含额外列时也会拒绝导入 |
overwrite |
将目标表改为与 package 一致。添加、重命名、移除(破坏性)、更改类型(破坏性)和重排列,并重命名表 |
overwrite-non-destructive |
执行与 overwrite 相同的变更,但遇到破坏性变更时停止导入并报告这些变更。不会写入任何内容 |
keep-existing 和 fail 都不会添加或重命名目标表中的列。缺少列时会拒绝导入,源端重命名的列也包括在内。要应用重命名,请使用 overwrite 或 overwrite-non-destructive。不会比较列顺序或表名称,列名称区分大小写。
破坏性变更指移除列或更改其类型。这些列中的值会被删除,其他列的数据会保留。重命名列不是破坏性变更,会保留其值。两种 overwrite 策略的变更都会影响使用该表的所有工作流。
n8n 2.44.0 之前导出的 package 不包含列 ID。对于这些 package,两种 overwrite 策略都会将重命名列视为先移除再添加,因此这是破坏性变更,也会被标记为破坏性变更。
如果 table ID 已存在于实例中的任意位置(包括其他 project),或其名称已被 target project 使用,创建 table 也会失败。使用 overwrite 策略重命名表时,如果新名称已被目标项目使用,也会以同样方式失败。
Tags 标签
Tag 在 n8n 中是 global 的,名称在整个实例中唯一。n8n 会按 source ID 匹配,而不是按名称匹配,因为只有跟踪稳定 ID,才能区分 rename 与 delete-and-recreate。新建 tag 会沿用 source ID。
冲突分为两类:
- Rename drift:ID 与 target 上的 tag 匹配,但名称不同,说明有人在其中一个实例上重命名了它。
- Name collision:Target 上不存在该 ID,但已有另一个 tag 使用相同名称。这在长期运行的实例中很常见,因为 tag 是各自独立创建的,ID 并不相关。
--tag-conflict-policy=rename 可以处理两种情况:对于 rename drift,它会将 tag 重命名为 package 中的名称;对于 name collision,它会将现有 tag 移到 package ID 上,同时保留其名称及已附加该 tag 的所有内容。唯一仍会拒绝的情况是发生 drift 的 tag 想采用的名称已被第三个 tag 使用。
n8n 更新 workflow 时,package 的 tag list 会完全替换 target workflow 的 tag,包括空 list。如果 workflow 完全没有 tag list,则 target 的 tag 保持不变。由于被丢弃的 tag 会在写入前过滤掉,因此更新 tagged workflow 时,如果 package 中的 tag 全部被丢弃,workflow 的 tag 就会被清空。如果希望 target tag 保持不变,请使用 --include-tags=false 进行 export。
Import 永远不会删除 tag。如果 target instance 关闭了 tag,所有 tag 处理都会被静默跳过,也不会导致 import 失败。
Folders 和 projects
--folder-conflict-policy=merge 会复用按 ID 匹配的 folder,并将 package content 合并到其中。Existing folder 会保留自己的名称,因此 merge 不会重命名任何内容。请注意,对于 merged folder,response 报告的是 package 中的 folder name,而不是 target 上的名称。
无论采用哪种 policy,两类 folder conflict 都会拒绝 import,因为它们意味着移动 folder,而不是合并:folder ID 已存在于另一个 project 中;或者 existing folder 的 parent 与 import 要放置的位置不同。
--folder-conflict-policy=overwrite 会让每个 project 与 package 保持一致。n8n 会从 project 根目录以及 package 定义的 folder 中,移除 package 既未包含、也未作为 sub-workflow 引用的 workflow。然后,它会移除 package 未定义的 folder,但仅在这些 folder 已为空时才会移除,因此仅存在于 target 上的 folder 中的 workflow 会保留。默认情况下,n8n 会归档被移除的 workflow,以便你恢复。使用 --overwrite-deletion-policy=hard-delete 时,它会永久删除该 workflow 及其执行记录。如果你无权删除 import 将要移除的某项内容,n8n 会拒绝 import,而不是只移除其中一部分。
对于 project package,n8n 会先创建 project shell,然后为每个 project 运行一次相同机制。如果 package project 的 ID 与 target 上的 personal project 匹配,import 会返回 403 并被拒绝;任何 conflict policy 都不能合并这种情况。
已归档的 workflows
Workflow 会连同其归档状态一起迁移。如果 workflow 在 package 中处于已归档状态,n8n 会以已归档状态创建新 workflow。使用 --conflict-policy=new-version 时,n8n 会归档或恢复现有 workflow,使其与 package 一致,这需要拥有删除该 workflow 的权限。使用 skip 时,现有 workflow 会保留其状态。已归档的 workflow 永远不会发布。
Node types 节点类型
n8n 会从 workflow 本身推断 package 需要的 node type,绝不会信任 manifest 中的 requirements.nodeTypes list。Manifest 可以让 import 更快,但不能改变判断结果。
使用默认的 --missing-node-type-mode=fail 时,如果 package 使用实例上不存在的 node type 或 node version,import 会在写入前被拒绝,并列出每个缺失类型及使用它的 workflow。使用 import-anyway 时,这些 workflow 会导入,但不会发布。
发布结果
Response 中的每个 workflow 都包含 publishing.state:
| State | 含义 |
|---|---|
published |
Workflow 已上线 |
unpublished |
按 policy 要求,workflow 未上线 |
unchanged |
未尝试 publish 或已跳过。现有 live version 会继续运行 |
blocked |
n8n 拒绝发布。blockedReason 会说明原因 |
failed |
已尝试 publish,但失败。error 会说明原因 |
blockedReason 为 stub-credential、incomplete-credential 或 missing-node-type。如果 workflow 同时因 credential 和缺失的 node type 被阻止,会报告 missing-node-type,因为它表示 workflow 实际上无法运行。
blocked 表示没有任何 version 上线。如果 workflow 已有 published version,而新 version 无法发布,则会得到 unchanged 和 skippedPublishReason,旧 version 会继续提供服务。因此,「never published」指刚导入的 version,而不是整个 workflow。
Publishing failure 永远不会导致 import 失败。Workflow 会完成导入,response 会说明它尚未上线。
Webhook path 冲突
两个 workflow 不能使用相同 HTTP method 注册同一个 webhook path。如果 package 要发布的两个 workflow 使用相同 path,第一个会发布,第二个会报告 failed,并显示消息 There is a conflict with one of the webhooks.。Import 本身仍会成功。如果 path 已被实例上已发布的 workflow 占用,也会出现相同情况。
n8n 只比较可以直接读取的 path:节点必须启用,path 必须是普通 value,而不是 expression,且不能包含 path parameter。由 expression 构建的 path、包含 parameter 的 path,以及 n8n 为每个 workflow 添加前缀的 webhook,不会以这种方式产生冲突。相同 path 使用不同 HTTP method 没有问题。
导入被拒绝的原因
每种会阻止 import 的原因都会以 type 出现在 issues array 中,部分原因还包含进一步限定的 kind:
| Type | Kinds | 含义 |
|---|---|---|
workflow-conflict |
Workflow 已存在于 target,且 --conflict-policy 为 fail |
|
workflow-lineage-conflict |
Target project 中有多个 workflow 是从 package 中同一个 workflow 导入的,因此 n8n 无法判断该更新哪一个。如果其中只有一个未归档,n8n 会更新那一个 | |
workflow-id-conflict |
新 workflow 的 package ID 已用于实例中的其他位置,包括其他 project 和 archived workflow | |
workflow-archive-forbidden |
Import 会归档或恢复某个现有 workflow,而你没有删除它的权限 | |
workflow-removal-forbidden |
--folder-conflict-policy=overwrite 或 --deleted-workflow-ids 会移除一个你无权删除的 workflow |
|
workflow-removal-conflict |
在选定内容 import 中,某个选定 workflow 的 target ID 同时出现在 --deleted-workflow-ids 中 |
|
folder-removal-forbidden |
--folder-conflict-policy=overwrite 会移除一个你无权删除的 folder |
|
workflow-folder-conflict |
Existing workflow 所在 folder 与 import 的目标 folder 不同,且 --conflict-policy=new-version 会更新它 |
|
project-conflict |
fail-policy |
Project 已存在,且 --project-conflict-policy 为 fail |
folder-conflict |
parent-mismatch、id-in-other-project、fail-policy |
无论采用哪种 policy,前两种都会拒绝 import |
credential-unresolved |
not_found、unknown_type、source_not_found、type_mismatch |
只有 not_found 可以通过 placeholder credential 解决 |
credential-conflict |
differs、divergent |
differs:package 会更改某个匹配的 credential,且 --credential-conflict-policy 为 fail。divergent:使用 overwrite 时,package 中两个名称或值不同的 credential 匹配到同一个 credential |
credential-update-forbidden |
使用 --credential-conflict-policy=overwrite 或 fail 时,你没有更新某个匹配 credential 的权限 |
|
credential-policy-violation |
实例 policy 拒绝 import 将要创建或更新的某个 credential,例如实例不允许的 credential type | |
data-table-unresolved |
missing、id-conflict、name-conflict、schema-incompatible、module-disabled、permission-denied |
使用 overwrite-non-destructive 时,schema-incompatible 表示变更将移除列或更改列类型,并列出这些列 |
tag-unresolved |
rename-drift、name-collision、invalid-name、invalid-id、permission-denied |
|
variable-unresolved |
引用的 variable 无法解析,且 --variable-missing-mode 为 must-preexist |
|
variable-conflict |
已解析 variable 的 value 不同,且 --variable-conflict-policy 为 fail |
|
variable-limit-exceeded |
新 variables 会超出实例的 variable limit | |
policy-violation |
实例 policy 拒绝 package 中的某个 workflow。n8n 会拒绝整个 import,而不是跳过该 workflow,因为其他 workflow 可能引用它 | |
missing-node-type |
使用 --missing-node-type-mode=fail 时,workflow 使用实例上不存在的 node type 或 version |
包含 agents 的 import 还可能返回 agent-conflict、agent-invalid、agent-dependency-unresolved 和 agent-policy-violation。
HTTP status 取决于问题类型。如果任一 issue 属于 conflict,response 就是 409:包括任何以 -conflict 结尾的 type、data table ID/name conflict,以及 tag rename drift/name collision。其他情况均为 422。如果混合的一组 issue 中包含一个 conflict,整个 response 都会返回 409。
有些 failure 会单独报告,而不是与其他问题一起批量返回,因为它们会在 n8n 制定计划前就停止处理:缺少 license 功能、缺少 API key scope,以及 package 格式错误。
如果你的角色不允许创建 tag,或创建、更改 data table,不会返回 403,而是作为 permission-denied blocking issue 返回,并指出所需的权限。缺少 API key scope 则始终返回 403。
后续阅读
- 导入 package:了解本页所述的选项。
- 限制和权限:了解 import 检查的 license 功能、scope 和 quota。
- Package 格式:了解 n8n 所读取文件的内容。