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/）建立：

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，內容：

{
  "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：安裝依賴

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 副本。安裝完成後執行：

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 已統一：

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

若輸出 zod OK 則繼續；若報 discriminator 錯誤，再次清理巢狀副本。

階段 5：建立資料目錄

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 並驗證

後臺啟動服務：

export N8N_USER_FOLDER=<n8n-data 絕對路徑>
cd <n8n-app 絕對路徑>
node node_modules/n8n/bin/n8n start

使用 run_in_background: true。等待 30-40 秒後驗證：

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，使用者首次訪問需註冊管理員賬號。

常見錯誤速查表

資源引用

• assets/start-n8n.txt — 桌面啟動指令碼模板（.txt 格式，使用時改名為 .bat）
• references/known-issues.md — 詳細的問題診斷與修復指南

解除安裝方法

想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。

# 停止 n8n 程序後刪除兩個目錄即可
rm -rf <n8n-app 目錄>
rm -rf <n8n-data 目錄>
rm <桌面>/啟動n8n.bat

質量不錯！部署步驟清晰有序，常見安裝問題都有預判和解決方案，基本能一次性部署成功。錯誤說明通俗易懂，對新手友好。缺點是檔案比較單一，缺少使用示例或演示影片。