Biz Deploy Vercel — 安全、一鍵部署網站至 Vercel
這個技能能將 1 個本地專案資料夾 (React / Next.js / Vite / 靜態 HTML) 變為 1 個在 Vercel 上的 Live URL，附帶 SSL、CDN 與預覽部署功能。目標：讓不會 DevOps 的獨立開發者 / 中小企業，只需透過與 Claude 對話就能部署 Landing Page。
精神：不問 Claude 可以自己檢查的東西。自動偵測框架、按需自動產生
vercel.json，只有在遇到真正的 手動門檻 (瀏覽器登入、自訂網域 DNS) 時才停下來。
何時使用
使用者想要：
- 將 Landing Page / 網站上線為 Live URL，以便分享、測試或投放廣告
- 修改程式碼後重新部署專案
- 為新 Repo 第一次設定 Vercel
- 設定自訂網域指向 Vercel
何時不使用
- 只需要本地建置，還不想公開 → 跳過，使用
npm run build/next dev。 - 需要部署到 Netlify / Cloudflare Pages / AWS → 此技能專注於 Vercel。
- 需要搭配自訂 GitHub Actions 的複雜 CI/CD → 仍可用此技能初始化專案，但自訂工作流程由使用者自行設定。
- 需要具狀態的完整 Node.js 後端 (WebSocket、Long Polling) → Vercel Serverless 不適合，請使用 Railway / Fly.io。
使用者會收到的輸出
- Live URL 格式
https://<project>.vercel.app(正式環境) 或預覽 URL。 - Inspect URL 格式
https://vercel.com/<account>/<project>/<deployment-id>，用來查看日誌。 - Project linked 記錄在
.vercel/project.json(已被 .gitignore 忽略) — 下次部署只需執行vercel --prod。 - 如果使用者要求自訂網域 → 提供具體的 DNS 設定指引 (A Record / CNAME)。
6 步驟工作流程
步驟 1 — 前置檢查：檢查 Vercel CLI / MCP
執行 scripts/check_vercel.sh (或內聯的等效指令) 來檢查以下 3 項狀態：
| 需要檢查的項目 | 指令 | 預期結果 |
|---|---|---|
| Node.js | node --version | v18+ 或 v20+ |
| Vercel CLI | vercel --version | 回傳版本號 (v32+) |
| Vercel 身份驗證 | vercel whoami | 回傳使用者名稱 |
如果缺少 Node.js：
- macOS：建議使用
brew install node或下載 https://nodejs.org - Windows：引導至 https://nodejs.org/en/download/ 下載 .msi 安裝程式
- Linux：使用
nvm install --lts或套件管理器。 - 暫停技能，等待使用者安裝完成後回報。
如果缺少 Vercel CLI：
- 偵測正在使用的套件管理器 (依序檢查
pnpm、yarn、npm，或讀取專案的 lockfile)。 - 全域安裝：
pnpm add -g vercel(若使用者使用 pnpm)npm install -g vercel(預設)
- 用
vercel --version再次驗證。
如果有 Vercel CLI 但未通過身份驗證 (vercel whoami 回報錯誤)：
- 執行
vercel login— 此指令會開啟瀏覽器，使用者必須點擊確認。這是 手動門檻，無法跳過。 - 通知使用者：「我已執行
vercel login。請開啟瀏覽器，點擊確認以完成驗證。完成後，請輸入 'ok' 讓我繼續。」 - 暫停，等待使用者回應。
如果使用者表示有 Vercel MCP：
- 檢查 MCP 伺服器，列出可用的 MCP 工具 (前綴為
mcp__vercel__*的工具)。 - 如果有 MCP，實際部署仍以 CLI 為優先 (CLI 對檔案上傳更穩定)，部署後若有需要，再使用 MCP 查詢專案 / 網域 / 環境變數。
- 如果使用者強制要求使用 MCP：請依照 https://vercel.com/docs/mcp 的文件進行身份驗證，然後使用對應的 MCP 工具。
步驟 2 — 偵測框架 + 專案結構
讀取專案根目錄的檔案以判斷框架：
| 檔案 | 框架 |
|---|---|
next.config.js / next.config.mjs / next.config.ts | Next.js |
vite.config.js / vite.config.ts | Vite (React/Vue/Svelte) |
package.json 包含 "react-scripts" | Create React App |
package.json 包含 "astro" | Astro |
package.json 包含 "@remix-run/dev" | Remix |
只有 index.html + 靜態資源，沒有 package.json | 靜態 HTML |
有 package.json 但不符合上述任何模式 | 詢問使用者是什麼框架，或交由 Vercel 自動偵測 |
另外記錄：
- 從
package.json(scripts.build) 獲取建置指令 - 輸出目錄 (Next:
.next，Vite:dist，CRA:build，靜態:.) - 所需 Node 版本 (從
engines.node或.nvmrc)
→ 讀取對應的參考文件：
- React/Vite →
references/react-vite.md - Next.js →
references/nextjs.md - 靜態 HTML →
references/static-html.md
步驟 3 — 按需產生 vercel.json
Next.js：Vercel 可以完全自動偵測，不需要 vercel.json，除非想要自訂標頭 / 重定向。
Vite / CRA (SPA 路由)：需要 vercel.json 將所有路由重寫到 index.html，以便客戶端路由正常運作：
{
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}
靜態 HTML：通常不需要。如果網站有多個頁面 (thank-you.html、privacy.html) 則不需要重寫。如果只有 index.html + JS 路由器，則需要像 SPA 那樣重寫。
安全性標頭 (建議用於正式環境)：
{
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
]
}
規則：只有當使用者真正需要時才建立 vercel.json。不必要的檔案 = Repo 雜訊。
步驟 4 — 部署前檢查清單
在執行 vercel 之前，請確認：
-
.gitignore中包含.vercel/、node_modules/、.env*(千萬不要提交機密) - 程式碼中的檔案路徑皆為 小寫 + 相對路徑 (Linux 區分大小寫)
- 沒有硬編碼的
localhostURL - 外部 Script/Stylesheet 都使用
https:// - 如果 Next.js 有環境變數 → 已準備好需要設定的環境變數清單
- 如果有
package.json→npm install(或等效指令) 能在本地成功執行
如果發現明顯問題 (例如 HTML 中硬編碼了 localhost)，先修正再進行部署。
步驟 5 — 部署
第一次部署專案 (還沒有 .vercel/project.json)：
vercel --prod --yes
--yes 旗標接受來自框架自動偵測的所有預設設定。Vercel 將會：
- 詢問 Scope (使用
--yes時會自動選取使用者的帳戶) - 偵測 Framework Preset
- 設定 Build Command 與 Output Directory
- 推送程式碼、建置、部署
如果需要自訂專案名稱，或使用者想連結到現有專案：
vercel link # 連結到現有專案 (互動式)
vercel --prod # 連結後部署
部署預覽 (非正式環境)：
vercel
→ 回傳格式為 https://<project>-<hash>.vercel.app 的預覽 URL，用於在提升為正式環境之前進行測試。
重新部署 (專案已連結)：
vercel --prod
擷取輸出 — 解析標準輸出以取得：
Production: https://<project>.vercel.appInspect: https://vercel.com/...
立即通知使用者這兩個 URL。
步驟 6 — 驗證 + 回報
部署成功後：
- HTTP 檢查 使用
curl -I https://<project>.vercel.app驗證 Live URL — 確認狀態碼 200 且 SSL 有效。 - 依照以下格式向使用者回報：
## ✅ 部署成功
**Live URL**：https://<project>.vercel.app
**Inspect / 日誌**：https://vercel.com/<account>/<project>/<deployment-id>
**框架**：<Next.js | Vite | CRA | 靜態 HTML>
**建置時間**：<Xs>
### 下次部署
只需執行：`vercel --prod`
### 選項
- 設定自訂網域 → 對我說 `setup domain <yourdomain.com>`
- 設定環境變數 → 對我說 `add env <KEY>`
- 查看日誌 → `vercel logs`
- 如果使用者要求自訂網域 → 讀取
references/domains.md並提供 DNS 設定指引。
邊緣情況與復原
Vercel 上建置失敗，但本地正常
常見原因：
- 大小寫敏感：在本地 Mac 上
import './Components/Header'可以執行，但如果實際資料夾是components，在 Linux 上會失敗。修正：根據實際大小寫重新命名。 - 缺少依賴：套件位於
devDependencies但執行時期需要 → 移到dependencies。 - Node 版本不符：在
package.json中加入"engines": { "node": "20.x" }或.nvmrc。
→ 使用 vercel logs <deployment-url> 取得日誌，閱讀、修正、重新部署。
專案已連結到錯誤的帳戶 / 專案
rm -rf .vercel/ 然後重新執行 vercel --prod --yes。或者使用 vercel link 選擇正確的專案。
正式環境的環境變數
vercel env add <KEY> production
# 出現提示時貼上值
vercel env pull .env.production.local # 如有需要，拉到本地
避免提交 .env* 檔案。如果尚未加入，請將其加入 .gitignore。
驗證過期
CLI 的 Token 可能會過期。如果 vercel whoami 回報未授權 → 重新執行 vercel login。
各框架的詳細參考資料
請根據專案的框架讀取對應的參考文件：
| 框架 | 參考文件 |
|---|---|
| Next.js (App / Pages Router) | references/nextjs.md |
| React (Vite / CRA) | references/react-vite.md |
| 靜態 HTML | references/static-html.md |
| 自訂網域 + DNS | references/domains.md |
| 錯誤與疑難排解 | references/troubleshooting.md |
原始參考資料
- Vercel CLI 文件：https://vercel.com/docs/cli
- Vercel 建置設定：https://vercel.com/docs/projects/project-configuration
- Vercel 限制 (免費方案)：https://vercel.com/docs/limits
- 狀態頁面：https://www.vercel-status.com