n8n 3.0 升级前体检：Migration Report、移除节点排查与 npm→Docker 迁移实操

先搞清楚自己站在哪：截至 2026 年 10 月初，n8n 最新稳定版是 2.41.4（9 月 30 日发布），beta 为 2.42.1，npm 与 Docker Hub 上还没有 3.x 正式包。官方提供 v3-rc（每周一重新打标）与 v3-nightly（每日）两个测试镜像通道供提前验证，并明确提示不要用于生产。要测试请固定一个具体 tag，别用会漂移的别名：

# 固定 tag 拉测试镜像（示例格式，以官方镜像页为准）
docker pull docker.n8n.io/n8nio/n8n:v3-rc
# 生产原则：任何环境都 pin 精确版本，例如 2.41.4，升级才改 tag

官方同时声明：breaking changes 页会随 3.0 临近持续更新。本篇内容核对自该页，动手前请再访问 docs.n8n.io 的 v3.0 breaking changes 页核对增量。

你的 2.x 实例自带体检工具：打开 Settings → Migration Report，n8n 会列出这份实例受 3.0 影响的具体项——包括被移除的节点、被删除的环境变量等。这份报告比任何通用清单都准，因为它扫的是你的真实工作流与配置。

一个典型发现：如果你设置过 N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION 环境变量，3.0 将删除它——外部 hook 抛错时不再创建执行记录，运行不会开始，也不计入 Insights 与授权用量。行为对绝大多数实例无感，但升级前应主动删掉该变量，避免依赖已删除配置的启动脚本报错。

3.0 移除的旧节点都有官方指定替代：Function 节点（legacy）换成 Code 节点的 Run Once for All Items 模式；Function Item 节点（legacy）换成 Code 节点的 Run Once for Each Item 模式；Item Lists 节点按你用的操作换成 Split Out、Aggregate、Sort、Limit、Remove Duplicates 或 Summarize；LangChain Code 节点（legacy）同样被移除。表达式侧，废弃的 $getPairedItem 助手被删除，改用标准 item linking（pairedItem 属性或 $("节点名").item）：

// Code 节点 · Run Once for All Items：整批处理
const items = $input.all();
return items.filter(i => i.json.status === "active");

// Code 节点 · Run Once for Each Item：单条处理，返回单个对象
const j = $input.item.json;
return { json: { id: j.id, name: String(j.name).trim() } };

AI Transform 节点比较特殊：升级时 n8n 会自动把已有节点迁移为 Code 节点并保留生成的 JavaScript，工作流不需要改；只是之后无法再新增 AI Transform 节点，新逻辑直接写 Code 节点。

# 导出全部工作流（CLI 参数以 n8n 官方文档为准）
n8n export:workflow --backup --output=workflows/
# 在导出目录全局搜这些关键词：
# "n8n-nodes-base.function"（Function 旧版）
# "n8n-nodes-base.itemLists"（Item Lists）
# "$getPairedItem"（表达式助手）

AI Agent 节点的版本 1 支持多种 agent 类型模式——SQL Agent、Conversational Agent、OpenAI Functions Agent、Plan and Execute Agent 与 ReAct Agent——3.0 将移除版本 1 及这些模式。官方给出的迁移路径：把使用 v1 的工作流与模板更新到最新版本节点；已经设为 Tools Agent 的工作流升级后行为不变；SQL Agent 场景改用 Postgres 或 MySQL 工具子节点，挂到较新版本的 AI Agent 节点上。

实操建议：先在列表里把所有含 AI Agent 节点的工作流筛出来，逐个确认节点版本与模式；ReAct 模式的提示词通常可以平移到新版节点的系统提示里，但工具调用行为有差异，迁移后要用真实输入回归一遍。

3.0 最重要的部署变更：自托管 n8n 将要求基于 Docker 的部署，npm 与 npx n8n 安装路线被取消，官方也不再往 npm 发布可运行的 n8n 包。还在用 npx n8n 配 PM2 或 systemd 的实例，必须在升级前完成容器化。官方推荐 Docker Compose 路线，分步迁移指南即将发布。关键技巧是把"换运行时"与"升版本"拆成两步——先在当前 2.x 版本上容器化并验证一切正常，再改 tag 升 3.0，否则出了问题分不清是谁的锅：

# docker-compose.yml —— 先 pin 你当前运行的 2.x 版本
services:
  n8n:
    image: n8nio/n8n:2.41.4   # 与当前版本一致，验证后再改 3.0
    restart: unless-stopped
    ports:
      - "5678:5678"
    volumes:
      - ./n8n-data:/home/node/.n8n
    environment:
      - GENERIC_TIMEZONE=Asia/Shanghai

好消息是迁移没有想象中疼：n8n 的有状态数据集中在一个 .n8n 目录（工作流、凭证、加密 key），停止服务、复制该目录、挂载进容器，起来就是同一台实例。本地开发可以用 Docker Compose，配好数据卷后体验与原来基本一致。

升级前做两份备份：.n8n 数据卷（凭证加密 key 就在里面，丢了凭证全部作废）与数据库。还有几处容易踩的细节：binaryData 目录改名为 storage——如果挂载了这个目录，升级时同步改挂载路径；Code 节点任务超时从 5 分钟收紧到 1 分钟，重活考虑拆分或挪到外部服务；未验证的社区节点与 Chat Hub 默认关闭，依赖它们的工作流升级后要先重新启用再验证；默认启用密钥轮换，旧凭证行为不受影响但值得留意。

回滚方案要提前演练：把生产 tag 改回旧版本号重启即可回到旧程序，但 n8n 的数据库迁移只向前——3.0 跑过之后直接改回旧 tag 可能读不了新结构的库。所以真正的回滚是"旧 tag 加恢复备份"的组合，备份的时效性决定你能回退多远：

# 回滚三步（演练时用测试实例验证）
# 1) 停容器
docker compose down
# 2) 恢复 .n8n 目录与数据库备份
# 3) 改回旧 tag 重启
#    image: n8nio/n8n:2.41.4
docker compose up -d