n8n 中文文档

n8n packages

提示

Feature availability 功能可用性

n8n packages 自 n8n 2.27.0 起可用。此后的大多数版本都添加了新选项,因此如果这里的某个选项无法识别,请检查你的 n8n 版本。

提示

Preview status 预览状态

n8n packages 处于 Preview 阶段。package 格式和 API 在未来版本中可能会发生变化,因此除非已经制定更新计划,否则不要将其用于关键自动化。

n8n package 是一个文件,其中包含 n8n 实例的一部分:若干工作流或 agents,以及它们运行所需的结构和引用。你可以从一个实例导出 package,将文件迁移后再导入另一个实例。可以把它理解为 n8n 实例某一部分的 npm package。

package 是扩展名为 .n8np 的 gzip 压缩 tar 归档。其中每个实体都是一个小型 JSON 文件,manifest.json 会列出 package 中包含的内容以及目标实例需要提供的内容。完整布局请参阅 Package 格式。

Packages 是一项 API 功能。你可以通过 n8n API 导出和导入,也可以使用封装了相同端点的 n8n CLI。n8n 编辑器无法导出或导入 package。

三种 package 形态

导出的对象决定 package 的形态,而形态决定内容在导入时的落点:

  • Workflow package 工作流 package:一个或多个工作流。导入时,它们会进入你选择的项目和文件夹。
  • Folder package 文件夹 package:一个或多个文件夹,始终包含其中嵌套的所有内容。导入时,文件夹树会进入你选择的项目。
  • Project package 项目 package:一个或多个完整项目。package 自带项目,因此会自行决定内容的落点,并忽略传入的任何目标项目。

一次导出可以同时包含工作流、agents 和文件夹;项目 package 会包含其项目中的 agents。工作流、agents 或文件夹都不能与项目一起导出。

Package 会携带哪些内容

会携带 不会携带
工作流:节点、连接、设置、发布状态和归档状态 凭据密钥以及大多数直接输入的值
文件夹及其嵌套关系 数据表行
项目:名称、描述和图标 执行和执行历史记录
凭据引用:ID、名称、类型以及通过表达式设置的字段 用户、项目成员、角色和共享关系
数据表模式:列 ID、名称和类型 固定数据和工作流静态数据
变量:名称、类型以及未明确排除的值 工作流版本历史记录
标签 工作流是否标记为收藏
Agents:定义、自定义工具、计划、skills 和渠道设置 Agent 渠道连接、会话和知识库文件

凭据密钥绝不会随 package 迁移。 package 中的凭据文件包含凭据的 ID、名称和类型。默认情况下,它还包含通过 n8n 表达式设置的字段(例如 ={{ $secrets.apiKey }})以及这些字段所依赖的设置。它绝不会包含密钥或其他直接输入的值,例如主机或区域。请参阅凭据值。导入时,n8n 会将每个引用匹配到目标实例上已有的凭据,或者创建一个凭据供你填写。

数据表行绝不会随 package 迁移。 只有模式会迁移。导入的数据表最初为空。

何时使用 packages

当你需要一种可重复、可自动化的方式在实例之间迁移内容时,请使用 packages:

  • 在环境之间提升。 将工作流作为流水线的一部分,从开发环境推送到预发布环境,再推送到生产环境。重复导入会就地更新,而不会创建重复项,因此同一条命令首次和后续都适用。
  • 迁移到新实例。 通过一个文件迁移项目及其文件夹和工作流。
  • 共享工作但不共享密钥。 将工作流交给另一个团队,而不必担心文件中包含凭据密钥。
  • 备份结构。 保存重建所需的工作流和结构,但 package 并不是完整备份:它不会携带执行数据。

快速开始

将 CLI 指向源实例,然后导出工作流:

n8n-cli config set-url https://source.example.com
n8n-cli config set-api-key <your-api-key>

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

将 CLI 指向目标实例,然后导入文件:

n8n-cli config set-url https://target.example.com
n8n-cli config set-api-key <your-api-key>

n8n-cli package import --file=triage.n8np --project-id=<target-project-id>

n8n 会在写入任何内容之前检查整个 package。如果存在会阻止导入的问题,例如工作流使用了目标实例没有的节点类型,命令会以非零状态退出,并一次性列出发现的所有问题。

本节内容

  • Package 格式:.n8np 文件中的内容:三种 package 形态、目录布局和 manifest。
  • 导出 package:将工作流、文件夹或整个项目导出为 .n8np package,并控制 n8n 处理子工作流依赖项的方式。
  • 导入 package:将 .n8np package 导入 n8n 实例,并控制内容的落点以及 n8n 解析依赖项的方式。
  • 导入的工作原理:本页说明调用 import 后,n8n 如何处理 n8n package:如何判断能否继续导入,以及如何解析每种 entity。
  • 限制和权限:导出或导入 package 时的大小限制、license 功能、API key scope,以及 n8n 发出的事件。

有关迁移工作流的其他方式,包括复制粘贴以及编辑器中的下载和导入选项,请参阅导出和导入。

相关资源

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