Package 格式
提示
Preview status 预览状态
n8n packages 处于 Preview 阶段。package 格式在未来版本中可能会发生变化。
n8n package 是 gzip 压缩的 tar 归档。标准工具可以读取它,因此无需 n8n 也能检查其内容:
tar -tzf triage.n8np # list what's inside
tar -xzf triage.n8np # extract it
.n8np 扩展名只是一种命名约定。n8n 在导入时不会检查文件名,也接受布局相同的未压缩 tar 文件。
在归档内,每个实体都以独立的小型 JSON 文件存放在自己的目录中,根目录下的 manifest.json 会为所有内容建立索引。manifest.json 必须是归档中的第一个文件,这样 n8n 才能在读取其余内容之前验证 package。
三种 package 形态
形态取决于导出的对象。三种形态携带的文件类型相同,但排列方式不同。
工作流 package
按工作流 ID 导出会得到若干独立工作流,其依赖的所有内容都位于顶层:
triage.n8np
├── manifest.json
├── workflows/
│ ├── triage-inbound-wf7Kq2/
│ │ ├── workflow.json
│ │ └── workflow-metadata.json
│ └── send-email-wf9Zx1/
│ ├── workflow.json
│ └── workflow-metadata.json
├── credentials/
│ └── linear-api-crLin44/
│ └── credential.json
├── variables/
│ └── slackchannelid-vaSl03/
│ └── variable.json
├── data-tables/
│ └── countries-dtCn12/
│ └── data-table.json
└── tags/
└── prod-tgPr01/
└── tag.json
每个工作流目录包含两个文件:
workflow.json:工作流本身。workflow-metadata.json:导出版本的 ID,以及源实例上已发布版本的 ID(如果有)。导入时会用它来应用发布策略。
文件夹 package
按文件夹 ID 导出会保留文件夹树。文件夹中的工作流位于该文件夹内的 workflows/ 目录中,嵌套文件夹则直接位于父文件夹内,不会重复出现 folders/ 路径段。凭据、变量、数据表和标签仍位于顶层:
in-progress.n8np
├── manifest.json
├── folders/
│ ├── to-production-fdToProd/
│ │ └── folder.json # an empty folder is just the shell
│ └── in-progress-fdInProg/
│ ├── folder.json
│ ├── workflows/
│ │ └── triage-inbound-wf7Kq2/
│ │ ├── workflow.json
│ │ └── workflow-metadata.json
│ └── nested-fdNest01/
│ ├── folder.json
│ └── workflows/
│ └── playground-wfPlay1/
│ ├── workflow.json
│ └── workflow-metadata.json
├── credentials/
│ └── linear-api-crLin44/
│ └── credential.json
└── tags/
└── prod-tgPr01/
└── tag.json
项目 package
按项目 ID 导出会增加一层命名空间。一个 package 可以携带多个项目。导出项目拥有的凭据、变量和数据表会嵌套在该项目下。全局内容或由 package 外项目拥有的内容仍位于顶层。标签始终位于顶层,因为标签在 n8n 中是全局的:
team-ligo.n8np
├── manifest.json
├── projects/
│ └── team-ligo-prTeam9/
│ ├── project.json
│ ├── workflows/ # workflows at the project root
│ │ └── triage-inbound-wf7Kq2/
│ │ ├── workflow.json
│ │ └── workflow-metadata.json
│ ├── folders/
│ │ └── in-progress-fdInProg/
│ │ ├── folder.json
│ │ └── workflows/
│ │ └── send-email-wf9Zx1/
│ │ ├── workflow.json
│ │ └── workflow-metadata.json
│ ├── credentials/ # owned by this project
│ │ └── linear-api-crLin44/
│ │ └── credential.json
│ ├── variables/ # scoped to this project
│ │ └── slackchannelid-vaSl03/
│ │ └── variable.json
│ └── data-tables/
│ └── countries-dtCn12/
│ └── data-table.json
├── credentials/ # a global credential
│ └── shared-smtp-crSmtp1/
│ └── credential.json
├── variables/ # a global variable
│ └── region-vaRg02/
│ └── variable.json
└── tags/ # always global
└── prod-tgPr01/
└── tag.json
提示
在项目 package 中,变量所在的位置决定其创建位置。projects/<project-directory>/variables/ 下的变量会在该项目中创建,顶层变量则会在全局创建。因此项目 package 不接受 --variable-parent-policy:布局已经作出了决定。
Agents 和 skills
Agents 与工作流并列存放。在工作流或文件夹 package 中,每个 agent 在顶层 agents/ 下都有一个目录。在项目 package 中,agent 位于其所属项目下的 projects/<project-directory>/agents/ 中。每个 agent 目录包含两个文件:
agent.json:agent 的定义,包括其自定义 tools 和计划。agent-metadata.json:导出版本的 ID,以及源实例上已发布版本的 ID(如果有)。导入时会用它来应用发布策略。
导出的 agent 使用的每个 skill 都有自己的目录,其中包含一个 skill.json,保存 skill 的内容以及它是项目 skill 还是实例 skill。如果项目 skill 所属的项目也在 package 中,该 skill 位于该项目下;其他所有 skill 都位于顶层 skills/ 中:
support.n8np
├── manifest.json
├── agents/
│ └── support-triage-agSup01/
│ ├── agent.json
│ └── agent-metadata.json
├── skills/
│ └── refund-policy-skRf01/
│ └── skill.json
└── credentials/
└── openai-account-crOai01/
└── credential.json
目录命名
每个实体都有一个名为 <slug>-<id> 的目录:先是实体名称生成的 slug,然后是连字符,最后是实体在源实例上的 ID。生成 slug 时,名称会转换为小写,删除除字母 a 到 z、数字、空白和连字符以外的所有字符,将连续空白和重复的连字符转换为单个连字符,并去掉两端的连字符:
| 实体名称 | ID | 目录 |
|---|---|---|
Triage inbound |
wf7Kq2 |
triage-inbound-wf7Kq2 |
slackChannelId |
vaSl03 |
slackchannelid-vaSl03 |
Q4 报告 |
wfQ4r1 |
q4-wfQ4r1 |
報告 |
wfBg02 |
workflow-wfBg02 |
最后一行展示了回退规则:如果生成 slug 后没有保留任何字符,n8n 会使用实体类型作为 slug(workflow、agent、skill、folder、project、credential、variable、data-table 或 tag)。由于 ID 是目录名的一部分,名称相同的两个实体仍会获得不同的目录。
目录名是为了方便用户阅读归档。n8n 始终通过 manifest 和 JSON 文件中的 ID 识别实体,而不会使用目录名。
manifest.json
manifest 是一个索引。它会告诉 n8n package 中包含什么,以及目标实例需要提供什么,使导入可以在不读取每个文件的情况下快速失败。
以下三个字段始终存在:
packageFormatVersion:package 格式的版本,当前为字符串"1"。sourceN8nVersion:创建 package 的 n8n 版本。sourceId:创建 package 的实例标识符。
随后是条目列表,每种存在的实体类型对应一个列表:workflows、agents、skills、folders、projects、credentials、dataTables、variables 和 tags。如果某个列表为空,则会完全省略。每个条目都包含相同的三个字段:
id:实体在源实例上的 ID。name:实体名称。target:包含实体 JSON 文件的目录,相对于 package 根目录。
工作流条目还包含 isArchived,表示该工作流在源实例上是否已归档。
最后是 requirements,其中列出工作流和 agents 在目标实例上运行所需的内容。它最多包含七个部分。每个条目都有 usedBy,即需要该内容的工作流和 agents,每项格式为 { "kind": "workflow", "id": "<id>" } 或 { "kind": "agent", "id": "<id>" }:
| 部分 | 条目结构 | 说明 |
|---|---|---|
credentials |
{ id, name, type, usedBy } |
打包的凭据最多只携带其表达式值,因此除非导入根据这些值创建凭据,否则目标实例必须提供该凭据 |
dataTables |
{ id, name, usedBy } |
模式本身位于打包的 data-table.json 中 |
workflows |
{ id, name, usedBy } |
子工作流和错误工作流引用,以及 agent 用作 tools 的工作流。name 为可选字段,因为导出用户可能看不到被引用的工作流 |
agents |
{ id, name, usedBy } |
agent 使用的 sub-agents。仅当 sub-agent 位于 package 中时才包含 name |
variables |
{ name, usedBy } |
仅包含名称,没有 ID,因为 $vars.<name> 在运行时按名称解析 |
tags |
{ id, name, usedBy } |
只有工作流使用标签 |
nodeTypes |
{ type, typeVersion, usedBy } |
工作流和 agents 的节点 tools 使用的每种节点类型和版本。目标实例必须安装所有这些节点,因此可通过该列表判断目标实例能否导入 package。导入时,n8n 会重新生成同一列表,而不是直接信任此处内容 |
警告
requirements 列出工作流和 agents 需要的内容,这与 package 实际包含的内容并不相同。requirements.workflows 会列出每个静态工作流引用,包括已打包在 package 中的子工作流。导出用户无权读取的凭据会出现在 requirements.credentials 中,但没有对应文件。不要将 requirements 视为归档清单;清单应查看各条目列表。
以下是包含两个工作流的工作流 package 的完整 manifest:
{
"packageFormatVersion": "1",
"sourceN8nVersion": "2.34.0",
"sourceId": "f9e1e962bba26edf357042c12f367dab17f4c63ec368e1f39cbf7ce43c8b9f8b",
"workflows": [
{ "id": "wf7Kq2", "name": "Triage inbound", "target": "workflows/triage-inbound-wf7Kq2", "isArchived": false },
{ "id": "wf9Zx1", "name": "Send email", "target": "workflows/send-email-wf9Zx1", "isArchived": false }
],
"credentials": [
{ "id": "crLin44", "name": "Linear api", "target": "credentials/linear-api-crLin44" }
],
"dataTables": [
{ "id": "dtCn12", "name": "countries", "target": "data-tables/countries-dtCn12" }
],
"variables": [
{ "id": "vaSl03", "name": "slackChannelId", "target": "variables/slackchannelid-vaSl03" }
],
"tags": [
{ "id": "tgPr01", "name": "prod", "target": "tags/prod-tgPr01" }
],
"requirements": {
"credentials": [
{ "id": "crLin44", "name": "Linear api", "type": "linearApi", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
],
"dataTables": [
{ "id": "dtCn12", "name": "countries", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
],
"workflows": [
{ "id": "wf9Zx1", "name": "Send email", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
],
"variables": [
{ "name": "slackChannelId", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
],
"tags": [
{ "id": "tgPr01", "name": "prod", "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] }
],
"nodeTypes": [
{ "type": "n8n-nodes-base.formTrigger", "typeVersion": 2.5, "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
{ "type": "n8n-nodes-base.linear", "typeVersion": 1, "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
{ "type": "n8n-nodes-base.executeWorkflow", "typeVersion": 1.2, "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
{ "type": "n8n-nodes-base.dataTable", "typeVersion": 1, "usedBy": [{ "kind": "workflow", "id": "wf7Kq2" }] },
{ "type": "n8n-nodes-base.emailSend", "typeVersion": 2.1, "usedBy": [{ "kind": "workflow", "id": "wf9Zx1" }] }
]
}
}
data-table.json
每个数据表文件包含该表的模式。行不会随 package 迁移。
{
"id": "dtCn12",
"name": "countries",
"columns": [
{ "id": "dcNm01", "name": "name", "type": "string", "index": 0 },
{ "id": "dcCd02", "name": "code", "type": "string", "index": 1 }
]
}
| 字段 | 描述 |
|---|---|
id |
表在源实例上的 ID。导入创建的表会保留该 ID |
name |
表的名称 |
columns |
每列对应一个条目,包含 id、name、type 和 index(列在表中的位置) |
columns[].id |
列在源实例上的 ID。n8n 2.44.0 之前导出的 package 不包含此字段 |
列 ID 让导入能够识别重命名的列,从而保留该列的值。n8n 2.44.0 之前导出的 package 不包含列 ID,因此 n8n 按名称匹配列,重命名列会被视为破坏性变更。请参阅数据表。
版本兼容性
packageFormatVersion 当前为 "1"。只有版本完全匹配时,n8n 实例才会导入 package。不存在兼容窗口或迁移路径:声明任何其他版本的 package 都会在写入任何内容之前以 400 被拒绝。
sourceN8nVersion 仅用于记录信息,不会与目标实例进行比较。因此,只要格式版本匹配且目标实例拥有工作流使用的节点类型,package 就可以在运行不同 n8n 版本的实例之间自由迁移。
例外是数据表列 ID。从 n8n 2.44.0 起,导出的数据表包含列 ID;旧实例会以 400 拒绝包含列 ID 的 package。请先升级导入目标实例。
在流水线中比较 packages
归档是确定性的:文件时间戳固定为 Unix 纪元,权限固定,gzip 以可移植模式运行。在同一实例和同一 n8n 版本上对相同内容执行两次导出会生成完全相同的字节,因此你可以在流水线中通过 package 校验和检测变化。
后续阅读
- 导出 package:了解如何生成三种 package 形态。
- 导入 package:了解控制内容落点的选项。
- 导入工作原理:了解 n8n 如何处理每个实体文件。