deploy-to-vercel

部署到 Vercel

將任何專案部署到 Vercel。一律部署為預覽（非正式環境），除非使用者明確要求正式環境。

目標是讓使用者進入最佳長期設定：他們的專案連結到 Vercel，並啟用 git push 自動部署。以下每種方法都試圖讓使用者更接近該狀態。

步驟 1：收集專案狀態

在決定使用哪種方法之前，先執行以下四項檢查：

# 1. 檢查是否有 git 遠端
 git remote get-url origin 2>/dev/null

# 2. 檢查是否已連結到 Vercel 專案（任一檔案存在即表示已連結）
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

# 3. 檢查 Vercel CLI 是否已安裝並通過驗證
vercel whoami 2>/dev/null

# 4. 列出可用的團隊（如果已驗證）
vercel teams list --format json 2>/dev/null

團隊選擇

如果使用者屬於多個團隊，請以項目符號列表呈現所有可用的團隊 slug，並詢問要部署到哪個團隊。一旦使用者選定團隊，立即進行下一步 — 無需額外確認。

在後續所有 CLI 指令中透過 --scope 傳遞團隊 slug（vercel deploy、vercel link、vercel inspect 等）：

vercel deploy [path] -y --no-wait --scope <team-slug>

如果專案已連結（.vercel/project.json 或 .vercel/repo.json 存在），這些檔案中的 orgId 決定了團隊 — 無需再次詢問。如果只有一個團隊（或僅個人帳戶），則跳過提示並直接使用。

關於 .vercel/ 目錄： 已連結的專案會有以下其中一個檔案：

• .vercel/project.json — 由 vercel link 建立（單一專案連結）。包含 projectId 和 orgId。
• .vercel/repo.json — 由 vercel link --repo 建立（基於儲存庫的連結）。包含 orgId、remoteName 和一個 projects 陣列，將目錄對應到 Vercel 專案 ID。

任一檔案存在即表示專案已連結。請檢查兩者。

請勿在未連結的目錄中使用 vercel project inspect、vercel ls 或 vercel link 來偵測狀態 — 如果沒有 .vercel/ 設定檔，它們會互動式提示（或加上 --yes 時，會靜默地連結作為副作用）。只有 vercel whoami 可以在任何地方安全執行。

步驟 2：選擇部署方法

已連結（.vercel/ 存在）+ 有 git 遠端 → Git Push

這是最理想的狀態。專案已連結並具有 git 整合。

1. 在推送前詢問使用者。 未經明確同意，絕不推送：

   此專案已透過 git 連線到 Vercel。我可以提交並推送以觸發部署。
   要繼續嗎？
   

2. 提交並推送：

   git add .
   git commit -m "deploy: <變更說明>"
   git push
   

   Vercel 會自動從推送建置。非正式分支會獲得預覽部署；正式分支（通常是 main）會獲得正式部署。

3. 取得預覽 URL。 如果 CLI 已驗證：

   sleep 5
   vercel ls --format json
   

   JSON 輸出包含一個 deployments 陣列。找到最新的項目 — 其 url 欄位即為預覽 URL。

   如果 CLI 未驗證，請告知使用者檢查 Vercel 儀表板或 git 提供者的提交狀態檢查以取得預覽 URL。

---

已連結（.vercel/ 存在）+ 無 git 遠端 → vercel deploy

專案已連結但沒有 git 儲存庫。直接使用 CLI 部署。

vercel deploy [path] -y --no-wait

使用 --no-wait 讓 CLI 立即返回部署 URL，而不是等待建置完成（建置可能需要一段時間）。然後使用以下指令檢查部署狀態：

vercel inspect <deployment-url>

對於正式部署（僅在使用者明確要求時）：

vercel deploy [path] --prod -y --no-wait

---

未連結 + CLI 已驗證 → 先連結，再部署

CLI 可正常運作但專案尚未連結。這是讓使用者進入最佳狀態的機會。

1. 詢問使用者要部署到哪個團隊。 以項目符號列表呈現步驟 1 中的團隊 slug。如果只有一個團隊（或僅個人帳戶），則跳過此步驟。

2. 一旦選定團隊，直接進行連結。 告知使用者將發生什麼事，但無需單獨確認：

   正在將此專案連結到 Vercel 上的 <團隊名稱>。這將建立一個 Vercel 專案
   以供部署，並在未來 git 推送時啟用自動部署。
   

3. 如果存在 git 遠端，使用基於儲存庫的連結並指定團隊範圍：

   vercel link --repo --scope <team-slug>
   

   這會讀取 git 遠端 URL 並比對到從該儲存庫部署的現有 Vercel 專案。它會建立 .vercel/repo.json。這比 vercel link（不帶 --repo）可靠得多，後者嘗試按目錄名稱比對，當本地資料夾和 Vercel 專案名稱不同時經常失敗。

   如果沒有 git 遠端，回退到標準連結：

   vercel link --scope <team-slug>
   

   這會提示使用者選擇或建立專案。它會建立 .vercel/project.json。

4. 然後使用最佳可用方法部署：

   • 如果存在 git 遠端 → 提交並推送（參見上方 git push 方法）
   • 如果沒有 git 遠端 → vercel deploy [path] -y --no-wait --scope <team-slug>，然後 vercel inspect <url> 檢查狀態

---

未連結 + CLI 未驗證 → 安裝、驗證、連結、部署

Vercel CLI 完全未設定。

1. 安裝 CLI（如果尚未安裝）：

   npm install -g vercel
   

2. 驗證：

   vercel login
   

   使用者在瀏覽器中完成驗證。如果在非互動式環境中無法登入，請跳到下方的無驗證備援方案。

3. 詢問要部署到哪個團隊 — 以項目符號列表呈現 vercel teams list --format json 中的團隊 slug。如果只有一個團隊/個人帳戶，則跳過。一旦選定，立即繼續。

4. 連結專案，使用選定的團隊範圍（如果存在 git 遠端則使用 --repo，否則使用一般的 vercel link）：

   vercel link --repo --scope <team-slug>   # 如果存在 git 遠端
   vercel link --scope <team-slug>          # 如果沒有 git 遠端
   

5. 部署，使用最佳可用方法（如果存在遠端則使用 git push，否則使用 vercel deploy -y --no-wait --scope <team-slug>，然後 vercel inspect <url> 檢查狀態）。

---

無驗證備援方案 — claude.ai 沙盒

使用時機： 最後手段，當 CLI 無法在 claude.ai 沙盒中安裝或驗證時。這不需要驗證 — 它會返回一個預覽 URL（即時網站）和一個認領 URL（轉移到您的 Vercel 帳戶）。

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]

參數：

• path - 要部署的目錄，或一個 .tgz 檔案（預設為當前目錄）

範例：

# 部署當前目錄
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh

# 部署特定專案
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project

# 部署現有 tarball
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz

該腳本會從 package.json 自動偵測框架，打包專案（排除 node_modules、.git、.env），上傳並等待建置完成。

告知使用者：「您的部署已準備就緒，位於 [previewUrl]。請前往 [claimUrl] 認領以管理您的部署。」

---

無驗證備援方案 — Codex 沙盒

使用時機： 在 Codex 沙盒中，CLI 可能未驗證。Codex 預設在沙盒環境中執行 — 先嘗試 CLI，如果驗證失敗則回退到部署腳本。

1. 檢查 Vercel CLI 是否已安裝（此檢查無需權限提升）：

   command -v vercel
   

2. 如果 vercel 已安裝，嘗試使用 CLI 部署：

   vercel deploy [path] -y --no-wait
   

3. 如果 vercel 未安裝，或 CLI 失敗並顯示「No existing credentials found」，使用備援腳本：

   skill_dir="<path-to-skill>"
   
   # 部署當前目錄
   bash "$skill_dir/resources/deploy-codex.sh"
   
   # 部署特定專案
   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
   
   # 部署現有 tarball
   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
   

該腳本處理框架偵測、打包和部署。它會等待建置完成並返回包含 previewUrl 和 claimUrl 的 JSON。

告知使用者：「您的部署已準備就緒，位於 [previewUrl]。請前往 [claimUrl] 認領以管理您的部署。」

**提升的網路存取：**僅在沙盒封鎖網路呼叫時才提升實際部署指令的權限（sandbox_permissions=require_escalated）。請勿提升 command -v vercel 檢查的權限。

---

代理特定注意事項

Claude Code / 終端機型代理

您擁有完整的 shell 存取權。請勿使用 /mnt/skills/ 路徑。按照上述決策流程直接使用 CLI。

對於無驗證備援方案，從技能安裝位置執行部署腳本：

bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]

路徑可能因使用者安裝技能的位置而異。

沙盒環境（claude.ai）

您可能無法執行 vercel login 或 git push。直接前往無驗證備援方案 — claude.ai 沙盒。

Codex

Codex 在沙盒中執行。先檢查 CLI 是否可用，然後回退到部署腳本。前往無驗證備援方案 — Codex 沙盒。

---

輸出

始終向使用者顯示部署 URL。

• Git push： 使用 vercel ls --format json 尋找預覽 URL。如果 CLI 未驗證，告知使用者檢查 Vercel 儀表板或提交狀態檢查。
• CLI 部署： 顯示 vercel deploy --no-wait 返回的 URL。使用 vercel inspect <url> 檢查建置狀態並向使用者報告。
• 無驗證備援方案： 同時顯示預覽 URL 和認領 URL：

  部署成功！
  
  預覽 URL：https://my-app-abc123.vercel.app
  認領 URL：https://vercel.com/claim-deployment?code=...
  
  在預覽 URL 檢視您的網站。
  若要將此部署轉移到您的 Vercel 帳戶，請前往認領 URL。
  

請勿使用 curl 或 fetch 驗證已部署的 URL 是否正常運作。只需返回連結。

---

疑難排解

網路出口錯誤（claude.ai）

如果因 claude.ai 的網路限制導致部署失敗，請告知使用者：

部署因網路限制而失敗。若要修正：

1. 前往 https://claude.ai/settings/capabilities
2. 將 *.vercel.com 加入允許的網域
3. 再次嘗試部署

提升的網路存取（Codex / 沙盒環境）

如果在沙盒環境中因網路問題（逾時、DNS 錯誤、連線重置）導致部署失敗，請使用提升的權限重新執行（sandbox_permissions=require_escalated）。請勿提升初始 CLI 可用性檢查的權限 — 僅提升實際部署指令的權限。

給使用者的範例說明：

部署需要提升的網路存取權限才能部署到 Vercel。我可以使用提升的權限
重新執行指令 — 要繼續嗎？

CLI 驗證失敗

如果 vercel login 或 vercel deploy 因驗證錯誤而失敗，請回退到無驗證部署腳本（取決於環境使用 claude.ai 或 Codex 版本）。