---

name: deploy-n8n

slug: deploy-n8n

version: 1.0.0

displayName: "一键部署 n8n"

description: "一键本地部署 n8n 工作流自动化平台并创建桌面启动快捷方式。This skill should be used when the user asks to install, deploy, set up, or run n8n locally on Windows. Covers npm-based installation with all known pitfalls pre-solved including zod version conflict and missing sqlite3, background service startup, and desktop shortcut creation."

summary: "一键本地部署 n8n 工作流自动化平台，预解 zod 冲突与 sqlite3 缺失，自动生成桌面启动脚本。"

triggers:

  - 部署n8n

  - 安装n8n

  - 启动n8n

  - 运行n8n

  - 本地部署n8n

  - n8n desktop

  - install n8n

  - deploy n8n

  - run n8n locally

agent_created: true

---



# deploy-n8n — 一键本地部署 n8n



## 用途



在 Windows 上本地部署 n8n 工作流自动化平台，包含：npm 安装、依赖冲突预处理、后台服务启动、桌面快捷方式生成。本技能已规避 n8n v2.x 在 Windows npm 安装时的所有已知坑点。



## 何时使用



- 用户要求安装、部署、运行 n8n

- 用户提到 "n8n"、"工作流自动化"、"workflow automation" 并希望本地使用

- 用户想在桌面放一个 n8n 启动图标



## 前置条件



- Node.js >= 20（推荐 v22 LTS）

- npm >= 10

- 约 1.5GB 磁盘空间（n8n 依赖较多）

- 网络可访问 npm registry



## 标准部署流程（严格按顺序执行）



### 阶段 1：创建项目目录与 package.json



在用户期望的安装位置（默认当前工作目录下的 `n8n-app/`）创建：



```bash

mkdir -p n8n-app

cd n8n-app

npm init -y

```



### 阶段 2：写入「坑点已规避」的 package.json



**关键：必须预先锁定 zod 版本为 3.25.67，否则 n8n v2.x 会因 zod 3.x/4.x 实例冲突而启动失败。**



用 Write 工具创建 `n8n-app/package.json`，内容：



```json

{

  "name": "n8n-app",

  "version": "1.0.0",

  "private": true,

  "dependencies": {

    "n8n": "^2.28.5",

    "sqlite3": "^5.1.7",

    "zod": "3.25.67"

  }

}

```



说明：

- `zod: 3.25.67`（精确版本，不带 ^）：n8n 的 @n8n/api-types 和 n8n-workflow 内部依赖 zod 3.25.67。若根目录装了 zod 4.x，会导致 `discriminatedUnion('__type', ...)` 抛出 "A discriminator value for key __type could not be extracted" 错误。锁定 3.25.67 可让所有子包共用根目录的同一个 zod 实例。

- `sqlite3`：n8n 默认使用 SQLite 作为数据库，但其 npm 包未把 sqlite3 列为自动安装的依赖，需手动加入。



### 阶段 3：安装依赖



```bash

cd n8n-app

npm install --no-audit --no-fund

```



此步耗时较长（n8n 有 2000+ 依赖，约 15-25 分钟）。使用 `run_in_background: true` 后台执行，完成后会自动通知。



### 阶段 4：清理残留的嵌套 zod 副本（保险措施）



即使 package.json 锁定了版本，npm 仍可能在某些子包的 node_modules 下放置 zod 副本。安装完成后执行：



```bash

cd n8n-app

find node_modules -maxdepth 5 -name "zod" -type d -path "*/node_modules/zod" -not -path "node_modules/zod" | while read d; do rm -rf "$d"; done

```



然后用以下命令验证 zod 已统一：



```bash

node -e "try { require('@n8n/api-types'); console.log('zod OK'); } catch(e) { console.error('FAIL:', e.message); }"

```



若输出 `zod OK` 则继续；若报 discriminator 错误，再次清理嵌套副本。



### 阶段 5：创建数据目录



```bash

mkdir -p ../n8n-data

```



n8n 的数据库、配置、加密密钥都存放在此目录（通过 N8N_USER_FOLDER 环境变量指定）。



### 阶段 6：创建桌面启动脚本



用 Write 工具在用户桌面创建 `启动n8n.bat`（路径：`C:\Users\<用户名>\Desktop\启动n8n.bat`）。模板见 `assets/start-n8n.txt`（存储为 .txt 以规避上传平台对可执行脚本的限制），使用时复制内容并保存为 `.bat` 文件。需替换以下占位符：



- `{{N8N_APP_DIR}}` — n8n-app 的绝对路径

- `{{N8N_DATA_DIR}}` — n8n-data 的绝对路径



脚本功能：双击即启动 n8n 服务，自动打开浏览器访问 http://localhost:5678，关闭窗口即停止服务。



**注意**：由于沙箱安全限制无法创建 .lnk 快捷方式，.bat 启动脚本是等效替代方案。如需 .lnk，可指导用户右键 .bat → 发送到 → 桌面快捷方式。



### 阶段 7：启动 n8n 并验证



后台启动服务：



```bash

export N8N_USER_FOLDER=<n8n-data 绝对路径>

cd <n8n-app 绝对路径>

node node_modules/n8n/bin/n8n start

```



使用 `run_in_background: true`。等待 30-40 秒后验证：



```bash

curl -s -o /dev/null -w "%{http_code}" http://localhost:5678

```



返回 `200` 表示启动成功。首次启动会执行约 100+ 个数据库迁移，日志中可见 "Editor is now accessible via: http://localhost:5678"。



### 阶段 8：打开浏览器



使用 present_files 工具呈现 `http://localhost:5678`，用户首次访问需注册管理员账号。



## 常见错误速查表



| 症状 | 原因 | 解决 |

|------|------|------|

| `discriminator value for key __type could not be extracted` | zod 版本冲突（3.x vs 4.x） | package.json 锁定 `zod: 3.25.67`，删除所有嵌套 zod 副本 |

| `Failed to load module "breaking-changes"` | 上述 zod 冲突的连锁反应 | 同上 |

| `SQLite package has not been found installed` | 缺少 sqlite3 依赖 | package.json 加入 `sqlite3` 依赖 |

| `Cannot find module '../package.json'` | n8n 安装不完整 | 等待 npm install 完全结束再启动 |

| 端口 5678 无响应 | 服务还在迁移数据库 | 首次启动需 30-60 秒，耐心等待 |

| MCP registry timeout | 外部网络问题，非致命 | 忽略，不影响本地使用 |



## 资源引用



- `assets/start-n8n.txt` — 桌面启动脚本模板（.txt 格式，使用时改名为 .bat）

- `references/known-issues.md` — 详细的问题诊断与修复指南



## 卸载方法



```bash

# 停止 n8n 进程后删除两个目录即可

rm -rf <n8n-app 目录>

rm -rf <n8n-data 目录>

rm <桌面>/启动n8n.bat

```