n8n 中文文档

导出 package

提示

Preview status 预览状态

n8n packages 处于 Preview 阶段。导出选项在未来版本中可能会发生变化。

导出操作会写入一个 n8n package,即 .n8np 归档。其中包含你请求的内容,以及这些工作流在目标实例上所需全部内容的引用。导出不会修改源实例。

使用 n8n CLI:

n8n-cli package export --workflow-id=<workflow-id> --output=triage.n8np

或者直接调用端点:

curl -X POST 'https://n8n.example.com/api/v1/n8n-packages/export' \
    -H "X-N8N-API-KEY: <your-api-key>" \
    -H 'Content-Type: application/json' \
    -d '{"workflowIds": ["<workflow-id>"]}' \
    -o triage.n8np

有关完整的请求和响应模式,请参阅端点参考中的 N8nPackage 部分。

选择导出内容

至少传入一个 ID。若要指定多个对象,请重复使用标志;不支持以逗号分隔的形式。

# Two workflows
n8n-cli package export --workflow-id=wf7Kq2 --workflow-id=wf9Zx1 --output=triage.n8np

# A folder, and everything nested inside it
n8n-cli package export --folder-id=fdInProg --output=in-progress.n8np

# A workflow and a folder together
n8n-cli package export --workflow-id=wf7Kq2 --folder-id=fdInProg --output=mixed.n8np

# A workflow and an agent together
n8n-cli package export --workflow-id=wf7Kq2 --agent-id=agSup01 --output=support.n8np

# Two whole projects
n8n-cli package export --project-id=prTeam9 --project-id=prOps3 --output=teams.n8np

工作流、agent 和文件夹 ID 可以组合使用。项目 package 的形态不同,因此项目 ID 不能与其中任何一种组合。混合这两组 ID 会返回 400。

文件夹始终会携带其中嵌套的文件夹及其工作流。文件夹和项目导出会排除已归档的工作流,除非设置 --include-archived-workflows=true。按 ID 指定的工作流即使已归档也始终会导出。如果指定的工作流也位于指定的文件夹中,它只会在该文件夹内导出一次。

n8n 将每组 ID 的上限设为 300。此限制按组计算,因此一次导出可以指定 300 个工作流、300 个 agents 和 300 个文件夹。超过上限会返回 400,而 CLI 不会在发送请求前捕获此问题。

空项目只会导出项目 metadata,manifest 中不会包含 workflows 列表。

导出标志

Flag 说明
--workflow-id, -w 要包含的工作流 ID。重复使用可导出多个工作流。
--agent-id 要包含的 agent ID。重复使用可导出多个 agents。
--folder-id 要包含的文件夹 ID,以及其中嵌套的所有内容。重复使用可导出多个文件夹。
--project-id, -p 要包含的项目 ID。重复使用可导出多个项目。不能与 --workflow-id、--agent-id 或 --folder-id 组合。
--output, -o package 的写入文件。默认为当前目录中的 export.n8np。
--version-policy latest(默认)、published-strict、prefer-published 或 ignore-unpublished。n8n 导出每个工作流和 agent 的哪个版本。请参阅工作流版本。
--include-variable-values true(默认)或 false。是否打包变量值。请参阅变量值。
--include-tags true(默认)或 false。是否打包导出工作流上的标签。
--include-archived-workflows false(默认)或 true。文件夹和项目导出是否包含其中已归档的工作流。
--credential-export-policy expression-values-only(默认)或 no-values。是否打包通过表达式设置的凭据字段。请参阅凭据值。
--dependency-policy fail(默认)、include-in-package 或 reference-only。n8n 如何处理 package 所依赖但你未指定的工作流或 agent,例如子工作流、错误工作流或 sub-agent。请参阅工作流依赖项。

提示

这里以 kebab-case 显示 n8n-cli package export 标志。--help 会输出等效的 camelCase 名称(--workflowId、--includeTags、--dependencyPolicy),错误消息也会使用这些名称。两种写法均有效。

--output 会覆盖已有文件且不发出警告。导出失败时 n8n 不会写入任何内容,因此失败的运行会保留之前的文件。

工作流依赖项

如果工作流调用子工作流或指定错误工作流,该工作流就是 package 的依赖项。当依赖项不在指定的 ID 集合中时,--dependency-policy 决定 n8n 如何处理。

该策略只适用于工作流和 agents,不影响它们使用的凭据、数据表、变量或标签。agent 的 sub-agents 以及它用作 tools 的工作流也算作依赖项。

值 行为
fail(默认) 中止导出并列出缺少的内容,最多 20 个 ID
include-in-package 遍历依赖关系图,并将缺少的工作流和 agents 添加到 package
reference-only 不包含这些对象,并将其记录在 requirements.workflows 或 requirements.agents 中,作为目标实例必须已有的实体

fail 和 include-in-package 会沿着整个依赖链处理。 如果工作流 A 调用 B,B 又调用 C,则导出 A 和 B 时仍会因 C 而失败。只有 reference-only 会停在直接引用处,因为它假定被引用的工作流及其依赖项已经一起存在于目标实例。

错误工作流也算作依赖项。 如果工作流在 Settings 设置 > Error workflow 错误工作流 下配置了错误工作流,则默认导出会失败,除非同时包含该错误工作流。例外情况是字面值 DEFAULT 和通过表达式设置的错误工作流,n8n 会忽略它们。

n8n 不会将表达式设置的引用视为依赖项,也不会在导入时重写此类引用。只有静态引用会计入。

日常环境提升场景有两种形式:

# Name the dependency yourself
n8n-cli package export --workflow-id=wf7Kq2 --workflow-id=wf9Zx1 --output=triage.n8np

# Or let n8n work it out
n8n-cli package export --workflow-id=wf7Kq2 \
    --dependency-policy=include-in-package \
    --output=triage.n8np

警告

导出项目时,include-in-package 可能会引入未请求的项目。由其他项目拥有的依赖项会将该项目的外壳和文件夹链带入归档。CLI 摘要统计的是你指定的项目,而不是归档中的项目,因此发生这种情况时会少报。请解压归档或读取 manifest,查看实际导出的内容。

工作流版本

--version-policy 决定每个工作流的哪个版本随 package 迁移:

值 行为
latest(默认) 导出当前草稿
published-strict 导出已发布版本。如果某个工作流没有已发布版本,则中止导出,并列出最多 20 个此类工作流
prefer-published 导出已发布版本;对于未发布的工作流,导出其草稿
ignore-unpublished 导出已发布版本,并排除未发布的工作流

对于工作流,该策略只决定节点和连接。其名称、设置和标签始终来自当前草稿。该策略也适用于 agents。

已归档的工作流没有已发布版本,因此无论策略如何,它始终导出其草稿。

被 ignore-unpublished 排除的依赖项视为缺失。在 --dependency-policy=fail 或 include-in-package 下,导出会中止;在 reference-only 下,n8n 会将其记录在 manifest 的 requirements 中。

变量值

默认情况下,导出工作流引用的变量会连同其值一起迁移。使用 --include-variable-values=false 时,变量仍会迁移并出现在 manifest 和 requirements.variables 中,但会省略其 value 字段。

关闭变量值会改变导入行为:目标实例会创建一个空变量,而不是填入变量值;这不会阻止变量本身迁移。

打包变量值需要 API key 具有 variable:list 作用域,但仅当导出的工作流引用至少一个变量时才需要。如果缺少该作用域,导出会返回 403,提示添加作用域或设置 --include-variable-values=false。任何可以创建 API key 的角色都能分配 variable:list,因此此处出现 403 表示所用 key 在创建时未包含该作用域。

n8n 会扫描节点参数和工作流设置中的 $vars.NAME、$vars['NAME'] 和 $vars["NAME"] 来查找变量引用。

如果同一 package 中的一个变量名会解析为两个不同变量,导出将被阻止,因为 package 只能携带其中一个。

凭据值

默认情况下,打包的凭据会携带值为 n8n 表达式的字段,例如 ={{ $secrets.apiKey }},以及这些字段所依赖的设置。例如,CA 证书字段只有在启用 SSL 时才会出现在凭据表单中,因此如果它包含表达式,SSL 设置也会一并迁移。你直接输入的其他值(例如主机或密码)永远不会迁移;出于安全原因,OAuth token 也不会迁移。使用 --credential-export-policy=no-values 时,每个凭据文件只包含凭据的 ID、名称和类型。

表达式值让目标实例能够创建一个可用的凭据,并从目标实例自己的存储中读取密钥。要使用这些值,请以 --credential-missing-mode=create-with-values 导入。请参阅凭据。

标签

使用 --include-tags=false 时,不会迁移任何标签数据:导出的工作流不携带标签引用,归档中也没有 tags/ 目录。

这对导入的影响比看起来更大。携带标签列表(包括空列表)的工作流会用该列表完全覆盖目标工作流的标签。完全不含标签列表的工作流则不会改变目标上的标签。因此,--include-tags=false 才是保留目标现有标签的选项。

如果源实例设置了 N8N_WORKFLOW_TAGS_DISABLED=true,无论该标志如何设置,每次导出都会省略标签且不发出警告。

响应包含哪些信息

导出成功时会以 application/gzip 返回归档,并通过 X-N8n-Export-Counts header 提供每种实体的实际数量:

X-N8n-Export-Counts: {"agents":0,"workflows":2,"folders":0,"credentials":1,"dataTables":1,"variables":1,"tags":1}

这些是计算文件夹内容以及自动包含的子工作流和 sub-agents 后,归档中最终各类内容的数量,因此不一定与请求的 ID 数量相符。该 header 没有 projects 键。CLI 会根据它输出摘要。

credentials 统计打包的凭据文件,因此无权读取的凭据会记录为要求,但不会计入数量。variables 统计打包的变量文件,而不是引用的名称。

无论导出了什么,下载文件名始终为 export.n8np。CLI 则会写入 --output 指定的位置。

权限

导出需要 API key 具有以下作用域:

  • 指定工作流或文件夹 ID 时,需要 workflow:export。文件夹使用工作流作用域。
  • 指定 agent ID 时,需要 agent:export。
  • 指定项目 ID 时,需要 project:export,这也涵盖这些项目中的 agents。
  • 打包变量值且工作流引用了至少一个变量时,需要 variable:list。

除了 API key 权限外,你只能导出自己有权读取的内容:n8n 在构建 package 时会检查你对每个工作流、agent、文件夹、项目和凭据的访问权限。无权读取的凭据会记录为要求,而不会打包。

导出不需要任何许可证功能。完整矩阵请参阅限制与权限。

错误

状态 原因
400 请求的工作流、agent、文件夹或项目不存在,或你无权访问;也可能是混合了不同 ID 组、未传入 ID、某组超过 300 个 ID,或者导出被 --dependency-policy 或 --version-policy=published-strict 阻止
403 API key 缺少所需作用域

实体不存在和无权访问都会返回相同的 400 和相同消息,因此不能使用导出来测试某个 ID 是否存在。导出绝不会返回 404。

错误正文只包含 message。

事件

每次导出都会在日志流和遥测路径上发出事件,以便审计从实例中导出了什么。

事件 发出时机
n8n.audit.n8n-package.export.success 导出成功
n8n.audit.n8n-package.export.failed 导出失败

成功事件包含用户,以及实际进入 package 的 workflowIds、agentIds、folderIds 和 projectIds,因此反映的是文件夹内容和自动包含的依赖项,而不是请求的对象。每个列表仅在非空时出现。

失败事件包含用户、请求的 ID,以及值为 access-denied、entity-not-found、blocked 或 validation 的 reason。

日志流事件包含 ID。遥测事件会发出计数,以保持数据匿名。

后续阅读

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。