PhuongDeveloper/landingpage

使用憑證的 Vercel CLI

使用 CLI 並採用基於憑證的身份驗證來部署和管理 Vercel 上的專案，無需依賴 vercel login。

步驟 1：找到 Vercel 憑證

在執行任何 Vercel CLI 指令之前，請先確認憑證的來源。請依序檢查以下情境：

A) 環境中已設定 VERCEL_TOKEN

printenv VERCEL_TOKEN

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

B) 憑證在 .env 檔案中，且變數名稱為 VERCEL_TOKEN

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

如果找到，請匯出它：

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

C) 憑證在 .env 檔案中，但變數名稱不同

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

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

檢查輸出內容，找出哪個變數包含憑證，然後將它匯出為 VERCEL_TOKEN：

export VERCEL_TOKEN=$(grep '^<變數名稱>=' .env | cut -d= -f2-)

D) 找不到憑證——詢問使用者

如果以上方法都沒有找到憑證，請使用者提供一個。他們可以在 vercel.com/account/tokens 建立 Vercel 存取憑證。

---

重要： 一旦 VERCEL_TOKEN 被匯出為環境變數，Vercel CLI 就會原生讀取它——請不要將它作為 --token 旗標傳遞。將機密資訊放在命令列引數中，會讓它們暴露在 shell 歷史記錄和行程清單中。

# 錯誤——憑證在 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——需要連結）

當你有憑證和團隊，但沒有預先存在的專案 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 推送部署——有 Git 遠端（建議）

Git 推送會觸發自動的 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 推送（如果你有推送權限）或 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 "值" | vercel env add VAR_NAME --scope <team-slug>

# 為特定環境設定（production、preview、development）
echo "值" | 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 快速資料傳輸，1 千萬次 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 原生讀取。
• 在詢問使用者之前，先檢查環境中是否有憑證。 先檢查目前的環境和 .env 檔案。
• 預設使用預覽部署。 僅在明確要求時才部署到正式環境。
• 在推送前先詢問使用者。 未經使用者批准，絕不推送提交。
• 不要直接修改 .vercel/ 檔案。 CLI 管理此目錄。讀取它們（例如驗證 orgId）是允許的。
• 不要 curl 或 fetch 已部署的 URL 來驗證。 只需將連結回傳給使用者。
• 使用 --format json，當結構化輸出有助於後續步驟時使用。
• 使用 -y，在會提示確認的指令上使用，以避免互動式阻塞。

故障排除

找不到憑證

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

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

驗證錯誤

如果 CLI 失敗並顯示 Authentication required：

• 憑證可能已過期或無效。
• 驗證：vercel whoami（使用環境中的 VERCEL_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