部署至 Vercel
將任何專案部署至 Vercel。除非使用者明確要求生產環境,否則一律部署為預覽(非生產環境)。
目標是讓使用者進入最佳長期設定:將他們的專案連結至 Vercel,並啟用 git push 部署。以下每種方法都試圖讓使用者更接近該狀態。
步驟 1:收集專案狀態
在決定使用哪種方法之前,執行所有四個檢查:
# 1. 檢查 git 遠端
出get 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 指令(vercel deploy、vercel link、vercel inspect 等)中,透過 --scope 傳遞團隊 slug:
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和一個將目錄映射至 Vercel 專案 ID 的projects陣列。
任一檔案都表示專案已連結。請檢查兩者。
請勿在未連結的目錄中,或沒有 .vercel/ 設定檔的情況下,使用 vercel project inspect、vercel ls 或 vercel link 來偵測狀態——它們會互動式地提示(或使用 --yes 時,會默默地連結作為副作用)。只有 vercel whoami 可以在任何地方安全執行。
步驟 2:選擇部署方法
已連結(.vercel/ 存在)+ 有 git 遠端 → Git Push
這是理想狀態。專案已連結並具有 git 整合。
-
在推送前詢問使用者。 未經明確同意,絕不推送:
此專案已透過 git 連線至 Vercel。我可以提交並推送以觸發部署。要繼續嗎? -
提交並推送:
git add . git commit -m "deploy: <變更說明>" git push
Vercel 會自動從推送中建置。非生產分支會獲得預覽部署;生產分支(通常是 `main`)會獲得生產部署。
3. **取得預覽 URL。** 如果 CLI 已驗證:
```bash
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 中的團隊 slug 以項目符號列表呈現。如果只有一個團隊(或僅個人帳戶),跳過此步驟。
-
選定團隊後,直接進行連結。 告知使用者將要執行的操作,但不要請求單獨確認:
正在將此專案連結至 <團隊名稱> 的 Vercel。這將建立一個 Vercel 專案以供部署,並在未來的 git push 時啟用自動部署。 -
如果存在 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。 -
然後使用最佳可用方法部署:
- 如果存在 git 遠端 → 提交並推送(參見上方 git push 方法)
- 如果沒有 git 遠端 →
vercel deploy [path] -y --no-wait --scope <team-slug>,然後執行vercel inspect <url>檢查狀態
未連結 + CLI 未驗證 → 安裝、驗證、連結、部署
Vercel CLI 完全未設定。
-
安裝 CLI(如果尚未安裝):
npm install -g vercel -
驗證:
vercel login使用者在瀏覽器中完成驗證。如果在無法登入的非互動式環境中執行,請跳至下方的無驗證後備方案。
-
詢問要部署到哪個團隊:將
vercel teams list --format json中的團隊 slug 以項目符號列表呈現。如果只有一個團隊/個人帳戶,則跳過。選定後立即繼續。 -
連結專案,使用所選的團隊範圍(如果存在 git 遠端則使用
--repo,否則使用純vercel link):vercel link --repo --scope <team-slug> # 如果存在 git 遠端 vercel link --scope <team-slug> # 如果沒有 git 遠端 -
部署,使用最佳可用方法(如果存在遠端則使用 git push,否則使用
vercel deploy -y --no-wait --scope <team-slug>,然後執行vercel inspect <url>檢查狀態)。
無驗證後備方案,claude.ai 沙箱
使用時機: 在 claude.ai 沙箱中無法安裝或驗證 CLI 時的最後手段。此方法不需要驗證。它會傳回一個預覽 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 沙箱
使用時機: 在 CLI 可能未驗證的 Codex 沙箱中。Codex 預設在沙箱化環境中執行,請先嘗試 CLI,如果驗證失敗,則回退到部署腳本。
-
檢查 Vercel CLI 是否已安裝(此檢查無需提權):
command -v vercel -
如果
vercel已安裝,嘗試使用 CLI 部署:vercel deploy [path] -y --no-wait -
如果
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 變體)。