帶有 Token 的 Vercel CLI

帶有 Token 的 Vercel CLI 是做什麼的？

使用 Token 驗證透過 CLI 部署和管理 Vercel 上的專案，無需依賴 vercel login。

步驟 1：找到 Vercel Token

在執行任何 Vercel CLI 指令之前，請先確認 Token 的來源。請依序嘗試以下情境：

A) 環境中已設定 VERCEL_TOKEN

printenv VERCEL_TOKEN

如果此指令有回傳值，代表已準備就緒。請跳至步驟 2。

B) Token 存在於 .env 檔案中，且變數名稱為 VERCEL_TOKEN

grep '^VERCEL_TOKEN=' .env 2>/dev/null

如果找到，請匯出它：

export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)

C) Token 存在於 .env 檔案中，但名稱不同

請尋找任何看起來像是 Vercel Token 的變數（Vercel Token 通常以 vca_ 開頭）：

grep -i 'vercel' .env 2>/dev/null

檢查輸出結果，找出哪個變數持有 Token，然後將其匯出為 VERCEL_TOKEN：

export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)

D) 未找到 Token — 詢問使用者

如果以上方法都未能取得 Token，請要求使用者提供。他們可以在 vercel.com/account/tokens 建立一個 Vercel 存取 Token。

---

重要： 一旦 VERCEL_TOKEN 被匯出為環境變數，Vercel CLI 會原生讀取它 — 請勿將其作為 --token 參數傳遞。將機密資訊放在命令列參數中會將其暴露於 Shell 歷史紀錄和處理程序列表中。

# 不好 — Token 會顯示在 Shell 歷史紀錄和處理程序列表中
vercel deploy --token "vca_abc123"

# 好 — CLI 會從環境變數讀取 VERCEL_TOKEN
export VERCEL_TOKEN="vca_abc123"
vercel deploy

步驟 2：找到專案與團隊

同樣地，請檢查專案 ID 與團隊範圍。這能讓 CLI 無需 vercel link 即可鎖定正確的專案。

# 檢查環境變數
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# 或檢查 .env
grep -i 'vercel' .env 2>/dev/null

如果你有專案 URL（例如 https://vercel.com/my-team/my-project），請擷取團隊 slug：

# 例如從 "https://vercel.com/my-team/my-project" 擷取 "my-team"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

如果你的環境中有 VERCEL_ORG_ID 和 VERCEL_PROJECT_ID，請匯出它們 — CLI 會自動使用這些變數，並略過任何 .vercel/ 目錄：

export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"

注意：VERCEL_ORG_ID 和 VERCEL_PROJECT_ID 必須同時設定 — 只設定其中一個會導致錯誤。

CLI 設定

確保 Vercel CLI 已安裝且為最新版本：

npm install -g vercel
vercel --version

部署專案

除非使用者明確要求，否則一律部署為預覽。請根據你擁有的資訊選擇方法。

快速部署（有專案 ID — 無需連結）

當環境中已設定 VERCEL_TOKEN 和 VERCEL_PROJECT_ID 時，可直接部署：

vercel deploy -y --no-wait

搭配團隊範圍（透過 VERCEL_ORG_ID 或 --scope）：

vercel deploy --scope <team-slug> -y --no-wait

生產環境（僅在明確要求時）：

vercel deploy --prod --scope <team-slug> -y --no-wait

檢查狀態：

vercel inspect <deployment-url>

完整部署流程（無專案 ID — 需要連結）

當你擁有 Token 和團隊，但沒有預先存在的專案 ID 時使用此方法。

先檢查專案狀態

# 專案是否有 git 遠端？
git remote get-url origin 2>/dev/null

# 是否已連結到某個 Vercel 專案？
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

連結專案

有 git 遠端（建議）：

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

會讀取 git 遠端並連接到對應的 Vercel 專案。建立 .vercel/repo.json。比單純的 vercel link（僅根據目錄名稱比對）更可靠。

沒有 git 遠端：

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

建立 .vercel/project.json。

連結到特定名稱的專案：

vercel link --project <project-name> --scope <team-slug> -y

如果專案已連結，請檢查 .vercel/project.json 或 .vercel/repo.json 中的 orgId，以確認其與目標團隊相符。

連結後進行部署

A) Git Push 部署 — 有 git 遠端（建議）

Git push 會自動觸發 Vercel 部署。

1. 在推送前詢問使用者。 未經明確同意絕對不要推送。
2. 提交並推送：

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

3. Vercel 會自動建置。非生產分支會獲得預覽部署。
4. 取得部署 URL：

   sleep 5
   vercel ls --format json --scope <team-slug>
   

   在 deployments 陣列中找到最新的條目。

B) CLI 部署 — 沒有 git 遠端

vercel deploy --scope <team-slug> -y --no-wait

檢查狀態：

vercel inspect <deployment-url>

從遠端儲存庫部署（未在本機複製程式碼）

1. 複製儲存庫：

   git clone <repo-url>
   cd <repo-name>
   

2. 連結到 Vercel：

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

3. 透過 git push（如果你有推送權限）或 CLI 部署進行部署。

關於 .vercel/ 目錄

已連結的專案會包含以下其一：

• .vercel/project.json — 來自 vercel link。包含 projectId 和 orgId。
• .vercel/repo.json — 來自 vercel link --repo。包含 orgId、remoteName 和一個 projects 對應表。

如果環境中同時設定了 VERCEL_ORG_ID 和 VERCEL_PROJECT_ID，則不需要此目錄。

請勿在未連結的目錄中執行 vercel project inspect 或 vercel link 來檢測狀態 — 它們會以互動方式提示或靜默地產生連結的副作用。vercel ls 是安全的（在未連結的目錄中，它預設會顯示該範圍的所有部署）。vercel whoami 在任何地方都是安全的。

管理環境變數

# 為所有環境設定
echo "value" | vercel env add VAR_NAME --scope <team-slug>

# 為特定環境設定（production, preview, development）
echo "value" | vercel env add VAR_NAME production --scope <team-slug>

# 列出環境變數
vercel env ls --scope <team-slug>

# 將環境變數拉取到本機 .env.local 檔案
vercel env pull --scope <team-slug>

# 移除變數
vercel env rm VAR_NAME --scope <team-slug> -y

檢視部署

# 列出最近的部署
vercel ls --format json --scope <team-slug>

# 檢視特定部署
vercel inspect <deployment-url>

# 檢視建置日誌（需要 Vercel CLI v35+）
vercel inspect <deployment-url> --logs

# 檢視執行時期請求日誌（預設會持續追蹤；加上 --no-follow 以取得一次性快照）
vercel logs <deployment-url>

管理網域

# 列出網域
vercel domains ls --scope <team-slug>

# 將網域新增至專案 — 已連結或具有環境變數連結的目錄（1 個參數）
vercel domains add <domain> --scope <team-slug>

# 新增網域 — 未連結的目錄（需要 <project> 位置參數）
vercel domains add <domain> <project> --scope <team-slug>

Stripe Projects 方案變更

如果此專案由 Stripe Projects 管理。在執行任何付費或破壞性的方案變更前請先詢問使用者 — 升級會實際扣款，降級則會移除席位。

首先執行 stripe projects status --json 以確認 Vercel 資源的本機名稱。以下範例假設使用預設名稱（vercel-plan）；如果它在 stripe projects add 時被重新命名，請使用實際名稱。

• 升級到 Pro： stripe projects add vercel/pro（或 stripe projects upgrade vercel-plan pro）
• 降級到 Hobby： stripe projects downgrade vercel-plan hobby

Pro 方案提供的功能

• 每月 $20 平台費用，包含每月 $20 的使用額度。
• 新專案預設使用 Turbo 建置機器（30 vCPU、60 GB 記憶體）— 建置速度比 Hobby 方案快非常多。
• 1 個部署席位 + 無限的免費 Viewer 席位（唯讀協作者、預覽評論）。
• 更高的包含配額（每月 1 TB 快速資料傳輸、1000 萬次 Edge 請求）。
• 可用的付費附加元件：SAML SSO、HIPAA BAA、Flags Explorer、Observability Plus、Speed Insights、Web Analytics Plus。

完整詳細資訊：https://vercel.com/docs/plans/pro-plan

工作規範

• 絕不要將 VERCEL_TOKEN 作為 --token 參數傳遞。 將其匯出為環境變數，讓 CLI 原生讀取。
• 在要求使用者提供 Token 之前，先檢查環境。 優先檢查目前的環境變數和 .env 檔案。
• 預設使用預覽部署。 僅在明確要求時才部署到生產環境。
• 在推送到 git 之前先詢問。 未經使用者同意絕不提交推送。
• 不要直接修改 .vercel/ 檔案。 CLI 會管理此目錄。讀取它們（例如為了驗證 orgId）是允許的。
• 不要使用 curl 或 fetch 來驗證已部署的 URL。 只需將連結回傳給使用者。
• 當結構化輸出有助於後續步驟時，請使用 --format json。
• 在會提示確認的命令上使用 -y，以避免被互動式阻塞。

疑難排解

找不到 Token

請檢查環境變數和任何存在的 .env 檔案：

printenv | grep -i vercel
grep -i vercel .env 2>/dev/null

驗證錯誤

如果 CLI 失敗並顯示 Authentication required：

• Token 可能已過期或無效。
• 驗證方式：vercel whoami（會使用環境變數中的 VERCEL_TOKEN）。
• 請使用者提供一個新的 Token。

錯誤的團隊

請確認範圍是否正確：

vercel whoami --scope <team-slug>

建置失敗

請檢查建置日誌：

vercel inspect <deployment-url> --logs

常見原因：

• 缺少相依性 — 確保 package.json 完整且已提交。
• 缺少環境變數 — 使用 vercel env add 新增。
• 框架設定錯誤 — 檢查 vercel.json。Vercel 會根據 package.json 自動偵測框架（Next.js、Remix、Vite 等）；如果偵測錯誤，可在 vercel.json 中覆寫。

CLI 未安裝

npm install -g vercel