前言¶

Vercel CLI 在本機終端裏通常先執行 vercel login，打開瀏覽器完成登錄，之後才能部署、改環境變量、看構建日誌。這條路徑在日常開發裏沒問題，但放到 CI、無圖形界面的服務器，或者讓 Cursor、Claude Code、Codex 這類 Agent 自己跑命令時，交互式登錄就會卡住：沒有人點瀏覽器，命令也會一直等輸入。

Vercel 官方文檔已經給出了非交互認證的辦法：在 Account Tokens 創建訪問令牌，然後用環境變量 VERCEL_TOKEN（或命令行 --token）讓 CLI 工作。vercel-cli-with-tokens 做的事情，就是把這套 Token 流程寫成 Agent 可執行的步驟：先找令牌、再定位項目和團隊、默認預覽部署、環境變量與域名也可以一併管理。它和同倉庫裏偏「一鍵部署」的 deploy-to-vercel 是互補關係，前者盯住 Token 認證和自動化場景，後者覆蓋交互登錄以及沙箱裏的無認證回退。

本文依據該 Skill 的 SKILL.md 原文，並對照 Vercel CLI、Access Tokens 官方文檔交叉覈實。Skill 元數據中的版本爲 1.0.0，作者字段爲 vercel。

這是什麼¶

vercel-cli-with-tokens 屬於 vercel-labs/agent-skills 倉庫，這是 Vercel 官方維護的 Agent Skills 集合，遵循通用的 SKILL.md 格式，Cursor、Codex CLI、Claude Code 等支持該格式的工具都可以加載。

Skill 自己的定位是：使用基於 Token 的認證，通過 Vercel CLI 部署和管理項目，不依賴 vercel login。官方 description 裏給出的觸發場景包括 "deploy to vercel"、"set up vercel"、"add environment variables to vercel"。也就是說，當你讓 Agent 去部署、初始化 Vercel 項目，或者給項目加環境變量時，它應當走 Token 這條路徑，而不是彈出登錄頁。

倉庫目錄在：

https://github.com/vercel-labs/agent-skills/tree/main/skills/vercel-cli-with-tokens

skills.sh 上也有對應條目：https://www.skills.sh/vercel-labs/agent-skills/vercel-cli-with-tokens

核心能力¶

對照 SKILL.md 和 Vercel CLI 文檔，這個 Skill 主要覆蓋下面幾件事。

1、按固定順序發現 Token。先看當前環境裏的 VERCEL_TOKEN，再看 .env 裏同名變量，再在 .env 裏搜名字帶 vercel 的項，都找不到才向用戶要。創建入口是 https://vercel.com/account/tokens 。

2、定位項目和團隊。讀取 VERCEL_PROJECT_ID、VERCEL_ORG_ID，或從項目 URL 裏抽出 team slug。兩個 ID 都在環境裏時，CLI 會直接用它們，不必再跑 vercel link。官方文檔也寫明：CI 或非交互環境裏應同時設置這兩個變量以跳過鏈接步驟。注意：VERCEL_ORG_ID 和 VERCEL_PROJECT_ID 必須成對出現，只設其中一個會報錯。

3、默認預覽部署。除非用戶明確要求生產環境，否則只做 preview。有項目 ID 時直接 vercel deploy；沒有則先 vercel link（有 git remote 時優先 --repo），再選擇 git push 或 CLI 部署。

4、管理環境變量、查看部署、配置域名。包括 vercel env add/ls/pull/rm、vercel inspect、vercel logs、vercel domains。

5、一組給 Agent 的約束。最重要的一條是：不要把 Token 寫成 --token 參數，只導出爲環境變量，讓 CLI 自己讀取。Vercel 官方文檔同樣建議 CI 使用 VERCEL_TOKEN，原因是命令行參數會出現在 shell 歷史和進程列表裏。官方 CLI 仍支持 --token，而且兩者同時存在時 --token 優先；這個 Skill 比 CLI 更嚴，直接禁止使用該參數。

安裝與啓用¶

Skill 倉庫的安裝方式是 Vercel Labs 的 skills CLI。只裝這一個 Skill：

npx skills add vercel-labs/agent-skills --skill vercel-cli-with-tokens

裝整個官方集合也可以：

npx skills add vercel-labs/agent-skills

npx skills add 會檢測本機已安裝的 Agent，並寫入對應目錄。默認是項目級安裝，加 -g 則裝到用戶目錄、對所有項目生效。常見工具的目錄如下（摘自 vercel-labs/skills 的 Supported Agents 表）：

指定工具時可以加 -a，例如同時寫入 Claude Code 和 Cursor：

npx skills add vercel-labs/agent-skills --skill vercel-cli-with-tokens -a claude-code -a cursor

安裝完成後，Agent 在識別到部署、配置 Vercel 這類任務時會加載該 Skill。本機還需要有 Vercel CLI：

npm install -g vercel
vercel --version

Token 從哪裏來¶

在跑任何 vercel 命令之前，Skill 要求先確認 Token 的來源，順序如下。

1、環境變量裏已經有 VERCEL_TOKEN：

printenv VERCEL_TOKEN

有值就可以進入下一步。

2、.env 裏寫了 VERCEL_TOKEN，則導出到當前 shell：

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

3、.env 裏用了別的變量名。Skill 建議按 vercel 關鍵字搜索，並把值導出爲 VERCEL_TOKEN。它在原文裏寫「Vercel token 通常以 vca_ 開頭」，這一點需要對照官方令牌格式來看：Vercel 在 2026 年 2 月的 changelog 裏說明，個人訪問令牌前綴是 vcp，vca 是 Sign in with Vercel 的 App Access Token。儀表盤 Access tokens 也寫明：個人訪問令牌以 vcp_ 開頭，創建後只顯示一次。給 CLI / CI 用的令牌，應當到 https://vercel.com/account/tokens 創建，而不是把 vca_ 的 App Token 當成通用 CLI 憑證。

4、以上都沒有，再向用戶要一份。令牌可以按賬戶、團隊或單個項目限定範圍；項目級令牌只能動那一個項目。

拿到之後只做環境變量導出，不要寫進命令行：

# 錯誤：Token 會出現在 shell 歷史和進程列表裏
vercel deploy --token "vcp_your_token"

# 正確：CLI 從環境變量讀取
export VERCEL_TOKEN="vcp_your_token"
vercel deploy

定位項目之後再部署¶

Token 就緒後，再確認項目和團隊：

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

如果手裏有項目 URL，例如 https://vercel.com/my-team/my-project，team slug 就是路徑的第一段 my-team，後續命令用 --scope <team-slug>。

兩個 ID 都有時，導出即可，CLI 會忽略目錄裏的 .vercel/：

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

已有項目 ID，直接部署（不需要 link）：

vercel deploy -y --no-wait

帶團隊範圍：

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

只有用戶明確要求生產環境時才加 --prod：

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

--no-wait 會立刻返回部署 URL，不等構建結束；狀態用下面這條查看：

vercel inspect <deployment-url>

沒有項目 ID，需要先 link。 先看倉庫狀態，不要用 vercel project inspect 或在未鏈接目錄裏跑 vercel link 來「探測」——它們可能彈出交互提示，或在帶 -y 時悄悄完成鏈接。Skill 認爲安全的探測命令是 vercel ls（未鏈接目錄下會列出該 scope 的部署）和任意位置的 vercel whoami。

git remote get-url origin 2>/dev/null
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

有 git remote 時優先倉庫級鏈接，它按 remote URL 匹配 Vercel 項目，比按目錄名匹配的普通 vercel link 更穩，完成後生成 .vercel/repo.json：

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

沒有 git remote 時：

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

這會生成 .vercel/project.json。也可以按項目名指定：

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

鏈接之後，有 git remote 的首選是 git push 觸發 Vercel 自動構建；推送前必須先問用戶，Skill 禁止在未批准時 git push。沒有 remote 則繼續用 vercel deploy --scope <team-slug> -y --no-wait。

.vercel/ 由 CLI 維護，可以讀裏面的 orgId 覈對團隊，但不要直接改這些文件。環境裏已經同時設置了 VERCEL_ORG_ID 和 VERCEL_PROJECT_ID 時，不需要這個目錄。

環境變量、日誌和域名¶

Skill 把項目環境變量的增刪查也寫進了同一套 Token 流程，命令都帶 --scope，避免落到錯誤團隊：

# 寫入所有環境
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>
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>

# 已鏈接或已通過環境變量指定項目時，只需域名
vercel domains add <domain> --scope <team-slug>

# 未鏈接目錄必須再帶項目名
vercel domains add <domain> <project> --scope <team-slug>

需要結構化輸出給後續步驟時，Skill 要求加上 --format json；會彈出確認的命令則加 -y，避免 Agent 卡在交互提示上。部署完成後把 URL 交給用戶即可，不要用 curl 去請求線上地址做「驗證」。

適用場景與注意事項¶

適合這類情況：CI / CD 流水線、無瀏覽器的服務器、以及 Agent 需要在本機或沙箱裏調用 Vercel CLI。令牌、項目 ID、團隊 ID 已經作爲密鑰進了環境或 .env 時，效果最直接。

和同集合裏的 deploy-to-vercel 可以一起看。deploy-to-vercel 的主路徑是 vercel whoami、vercel login、按是否已鏈接選擇 git push 或 vercel deploy，並在 claude.ai / Codex 沙箱裏提供無認證的 claimable 部署腳本。vercel-cli-with-tokens 不走登錄頁，專門處理 Token、環境變量發現，以及「有 ID 就直接部署、沒 ID 再 link」的細節。兩者都默認預覽部署、推 git 前要詢問、不要 curl 部署 URL。

使用時有幾處容易踩坑。

1、認證失敗。CLI 報 Authentication required 時，先 vercel whoami 確認當前環境裏的 VERCEL_TOKEN 是否仍有效；過期或被吊銷就需要重新到儀表盤創建。團隊不對時用 vercel whoami --scope <team-slug> 覈對。

2、構建失敗。用 vercel inspect <deployment-url> --logs 看日誌。Skill 列出的常見原因包括：package.json 依賴不完整或沒提交、環境變量沒配、框架識別不對。Vercel 會從 package.json 自動識別 Next.js、Remix、Vite 等，識別錯了再在 vercel.json 裏覆蓋。

3、不要用探測命令誤鏈項目。未鏈接目錄裏不要跑 vercel project inspect 或隨意 vercel link。

4、令牌當密鑰對待。創建後只顯示一次；官方建議放進密鑰管理或環境變量，不要提交進倉庫。Vercel 已對泄露到公開 GitHub 倉庫、gist、npm 包的憑證做 secret scanning，並可能自動吊銷。

5、如果項目由 Stripe Projects 管理，Skill 要求在做付費或破壞性套餐變更之前先問用戶。升級會真實扣費，降級會去掉席位。這和部署本身不是同一件事，但原文寫在同一份 SKILL.md 裏。

小結¶

vercel-cli-with-tokens 解決的是一件很具體的事：在不能（或不該）執行 vercel login 的環境裏，讓 Agent 用 VERCEL_TOKEN 調用 Vercel CLI，完成預覽部署、環境變量和域名管理。關鍵約束也很清楚：Token 只走環境變量、默認 preview、成對使用 org/project ID、改 git 遠程之前先問人。

官方地址：

• Skill 目錄：https://github.com/vercel-labs/agent-skills/tree/main/skills/vercel-cli-with-tokens
• 集合倉庫：https://github.com/vercel-labs/agent-skills
• skills.sh：https://www.skills.sh/vercel-labs/agent-skills
• Vercel CLI 與 Token：https://vercel.com/docs/cli 、https://vercel.com/docs/cli/global-options
• 創建訪問令牌：https://vercel.com/docs/accounts/access-tokens