vercel-cli-with-tokens

Vercel CLI 搭配 Token

使用 CLI 搭配 Token 驗證在 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

如果你有專案網址（例如 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 remote？
git remote get-url origin 2>/dev/null

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

連結專案

有 git remote（建議）：

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

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

沒有 git remote：

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 remote（建議）

Git push 會觸發自動 Vercel 部署。

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

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

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

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

   在 deployments 陣列中找到最新的一筆。

B) CLI 部署 — 沒有 git remote

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（如果你有 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 檔案。
• 預設使用預覽部署。 僅在明確要求時才部署到生產環境。
• 在 push 到 git 前先詢問。 未經使用者同意絕不 push 提交。
• 不要直接修改 .vercel/ 檔案。 CLI 會管理此目錄。讀取它們（例如驗證 orgId）是允許的。
• 不要使用 curl/fetch 來驗證已部署的網址。 只需將連結回傳給使用者。
• 使用 --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