前言¶

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