vercel-cli

Vercel CLI 技能

Vercel CLI（vercel 或 vc）可從命令列部署、管理及開發 Vercel 平台上的專案。使用 vercel <command> --help 查看任何指令的完整旗標詳細資訊。

已安裝的 CLI 說明是晦澀或新增旗標的唯一正確來源。如果此處的指令範例不足，請先執行 vercel <command> --help 再行動，不要自行猜測。

僅解析 stdout 中的 URL 和 JSON。警告、進度及 --help 會輸出到 stderr；只有在搜尋說明文字時才合併串流。部分說明指令在印出使用方式後會以 exit 2 結束，因此請將印出的使用方式視為成功的說明讀取。

在 agent/非互動模式下，許多指令會將錯誤和必要確認以單一 JSON 物件輸出到 stdout，包含 status、reason、hint 和 next（可執行的後續指令）。建議優先執行建議的 next 指令，而非自行組合重試。讀取類指令（如 list、logs、inspect 和 api）則維持正常輸出格式。

關鍵：專案連結

指令必須從包含 .vercel 資料夾的目錄（或其子目錄）執行。.vercel 的設定方式取決於你的專案結構：

• .vercel/project.json：由 vercel link 建立。連結單一專案。適用於單一專案的儲存庫，若 monorepo 中只有一個專案也可運作。
• .vercel/repo.json：由 vercel link --repo 建立。連結可能包含多個專案的儲存庫。當任何專案位於非根目錄（例如 apps/web）時，這總是好的做法。

從專案子目錄（例如 apps/web/）執行時，會跳過「選擇專案」提示，因為沒有歧義。

當發生問題時，先檢查連結方式——查看 .vercel/ 中的內容是 project.json 還是 repo.json。同時用 vercel whoami 確認你所在的團隊是否正確——在錯誤的團隊下進行連結是常見錯誤。

快速開始

npm i -g vercel
vercel login
vercel link              # 單一專案
# 或
vercel link --repo       # monorepo
vercel pull
vercel dev        # 本地開發
vercel deploy     # 預覽部署
vercel --prod     # 正式部署

決策樹

使用此決策樹導向正確的參考檔案：

• 部署、重新部署、強制建置、無快取建置，或部署來源/溯源 → references/deployment.md
• 滾動發布、部署鉤子、Cron 任務、快取、Git 連線、Edge Config、重新導向、自訂環境 → references/project-infra.md
• 本地開發 → references/local-development.md
• 環境變數 → references/environment-variables.md
• CI/CD 自動化 → references/ci-automation.md
• 網域或 DNS → references/domains-and-dns.md
• 專案或團隊 → references/projects-and-teams.md
• 建置失敗、部署錯誤、日誌、指標、Speed Insights、Core Web Vitals、活動、效能、預覽存取或正式除錯 → references/monitoring-and-debugging.md
• 警示、用量、合約、帳單購買、Token、遙測或 CLI 升級 → references/platform-ops.md
• Blob 儲存 → references/storage.md
• Container Registry（vercel vcr：儲存庫、映像、標籤、docker/podman/buildah 登入、推送/拉取） → references/container-registry.md
• 整合（資料庫、儲存等） → references/integrations.md
• 連接器（vercel connect） → references/connectors.md
• 路由規則 → references/routing.md
• 防火牆（WAF 規則、IP 封鎖、速率限制） → references/firewall.md
• 存取預覽部署 → 使用 vercel curl（參見 references/monitoring-and-debugging.md）
• CLI 指令不可用或輸出缺少必要欄位 → 當第一級 CLI 路徑不可用或不夠時，使用 vercel api（參見 references/advanced.md）
• Node.js 後端（Express、Hono 等） → references/node-backends.md
• Monorepo（Turborepo、Nx、workspaces） → references/monorepos.md
• Bun 執行環境 → references/bun.md
• 功能旗標 → references/flags.md
• 微前端 → references/microfrontends.md
• Sandbox → references/sandbox.md
• Agent、MCP、技能探索或 AI Gateway → references/agent-and-ai.md
• 捕獲的請求追蹤（vercel traces，包含 --open / --view） → references/advanced.md
• Vercel Apps / OAuth 應用程式（vercel oauth-apps） → references/advanced.md
• 進階（vercel api 備援、webhooks） → references/advanced.md
• 全域旗標 → references/global-options.md
• 首次設定 → references/getting-started.md

反模式

• 在含有多個專案的 monorepo 中使用錯誤的連結類型：vercel link 會建立 project.json，僅追蹤一個專案。請改用 vercel link --repo。當出問題時，先檢查 .vercel/。
• 讓指令在 monorepo 中自動連結：許多指令在 .vercel/ 不存在時會隱含執行 vercel link。這會建立 project.json，可能是錯誤的。請先明確執行 vercel link（或 --repo）。
• 在錯誤的團隊下進行連結：使用 vercel whoami 檢查，使用 vercel teams switch 切換。
• 在純 CI 執行中忘記非互動旗標：偵測到的 agent 預設會加上 --non-interactive，但純 CI 不會——請明確傳入，並只在需要確認的指令加上 --yes。
• 在 vercel build 後使用 vercel deploy 但未加 --prebuilt：建置輸出會被忽略。
• 使用 vercel redeploy 進行無快取重建：vercel redeploy 沒有無快取旗標；需要全新部署且不保留建置快取時，請使用 vercel deploy --force 且不加 --with-cache。
• 在旗標中硬編碼 Token：使用 VERCEL_TOKEN 環境變數代替 --token。
• 停用部署保護：改用 vercel curl 存取預覽部署。
• 過早使用 vercel api：當第一級 CLI 指令能提供所需資料或操作時，優先使用它們。