vercel-cli-with-tokens by vercel-labs/agent-skills
npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-cli-with-tokens使用基于令牌认证的 CLI 在 Vercel 上部署和管理项目,无需依赖 vercel login。
在运行任何 Vercel CLI 命令之前,先确定令牌的来源。请按顺序处理以下场景:
VERCEL_TOKEN 已在环境中设置printenv VERCEL_TOKEN
如果返回一个值,说明已准备就绪。跳转到步骤 2。
.env 文件中的 VERCEL_TOKEN 下grep '^VERCEL_TOKEN=' .env 2>/dev/null
如果找到,将其导出:
export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
.env 文件中,但变量名不同广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
查找任何看起来像 Vercel 令牌的变量(Vercel 令牌通常以 vca_ 开头):
grep -i 'vercel' .env 2>/dev/null
检查输出以确定哪个变量保存着令牌,然后将其导出为 VERCEL_TOKEN:
export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
如果以上方法都没有找到令牌,请要求用户提供一个。他们可以在 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
同样地,检查项目 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 必须一起设置 — 只设置其中一个会导致错误。
确保已安装 Vercel CLI:
npm install -g vercel
vercel --version
除非用户明确请求生产环境,否则始终部署为预览环境。根据你拥有的信息选择方法。
当环境中设置了 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 时使用此方法。
# 项目是否有 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 推送会触发自动的 Vercel 部署。
推送前询问用户。 未经明确批准,切勿推送。
提交并推送:
git add .
git commit -m "deploy: <description of changes>"
git push
Vercel 自动构建。非生产分支会获得预览部署。
获取部署 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>
克隆仓库:
git clone <repo-url>
cd <repo-name>
链接到 Vercel:
vercel link --repo --scope <team-slug> -y
通过 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 ls、vercel project inspect 或 vercel link 来检测状态 — 它们会交互式地提示或产生静默链接的副作用。只有 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 文件
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 logs <deployment-url>
# 列出域名
vercel domains ls --scope <team-slug>
# 向项目添加域名
vercel domains add <domain> --scope <team-slug>
VERCEL_TOKEN 作为 --token 标志传递。 将其导出为环境变量,让 CLI 原生读取。.env 文件。.vercel/ 文件。 CLI 管理此目录。--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 logs <deployment-url>
常见原因:
package.json 完整且已提交。vercel env add 添加。vercel.json。Vercel 根据 package.json 自动检测框架(Next.js、Remix、Vite 等);如果检测错误,请用 vercel.json 覆盖。npm install -g vercel
每周安装量
3.7K
仓库
GitHub Stars
23.8K
首次出现
7 天前
安全审计
安装于
codex3.4K
opencode3.3K
gemini-cli3.3K
cursor3.3K
github-copilot3.3K
cline3.3K
Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on vercel login.
Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
VERCEL_TOKEN is already set in the environmentprintenv VERCEL_TOKEN
If this returns a value, you're ready. Skip to Step 2.
.env file under VERCEL_TOKENgrep '^VERCEL_TOKEN=' .env 2>/dev/null
If found, export it:
export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
.env file under a different nameLook for any variable that looks like a Vercel token (Vercel tokens typically start with vca_):
grep -i 'vercel' .env 2>/dev/null
Inspect the output to identify which variable holds the token, then export it as VERCEL_TOKEN:
export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.
Important: Once VERCEL_TOKEN is exported as an environment variable, the Vercel CLI reads it natively — do not pass it as a--token flag. Putting secrets in command-line arguments exposes them in shell history and process listings.
# Bad — token visible in shell history and process listings
vercel deploy --token "vca_abc123"
# Good — CLI reads VERCEL_TOKEN from the environment
export VERCEL_TOKEN="vca_abc123"
vercel deploy
Similarly, check for the project ID and team scope. These let the CLI target the right project without needing vercel link.
# Check environment
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID
# Or check .env
grep -i 'vercel' .env 2>/dev/null
If you have a project URL (e.g. https://vercel.com/my-team/my-project), extract the team slug:
# e.g. "my-team" from "https://vercel.com/my-team/my-project"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
If you have bothVERCEL_ORG_ID and VERCEL_PROJECT_ID in your environment, export them — the CLI will use these automatically and skip any .vercel/ directory:
export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"
Note: VERCEL_ORG_ID and VERCEL_PROJECT_ID must be set together — setting only one causes an error.
Ensure the Vercel CLI is installed:
npm install -g vercel
vercel --version
Always deploy as preview unless the user explicitly requests production. Choose a method based on what you have available.
When VERCEL_TOKEN and VERCEL_PROJECT_ID are set in the environment, deploy directly:
vercel deploy -y --no-wait
With a team scope (either via VERCEL_ORG_ID or --scope):
vercel deploy --scope <team-slug> -y --no-wait
Production (only when explicitly requested):
vercel deploy --prod --scope <team-slug> -y --no-wait
Check status:
vercel inspect <deployment-url>
Use this when you have a token and team but no pre-existing project ID.
# Does the project have a git remote?
git remote get-url origin 2>/dev/null
# Is it already linked to a Vercel project?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
With git remote (preferred):
vercel link --repo --scope <team-slug> -y
Reads the git remote and connects to the matching Vercel project. Creates .vercel/repo.json. More reliable than plain vercel link, which matches by directory name.
Without git remote:
vercel link --scope <team-slug> -y
Creates .vercel/project.json.
Link to a specific project by name:
vercel link --project <project-name> --scope <team-slug> -y
If the project is already linked, check orgId in .vercel/project.json or .vercel/repo.json to verify it matches the intended team.
A) Git Push Deploy — has git remote (preferred)
Git pushes trigger automatic Vercel deployments.
Ask the user before pushing. Never push without explicit approval.
Commit and push:
git add .
git commit -m "deploy: <description of changes>"
git push
Vercel builds automatically. Non-production branches get preview deployments.
Retrieve the deployment URL:
sleep 5
vercel ls --format json --scope <team-slug>
Find the latest entry in the deployments array.
B) CLI Deploy — no git remote
vercel deploy --scope <team-slug> -y --no-wait
Check status:
vercel inspect <deployment-url>
Clone the repository:
git clone <repo-url>
cd <repo-name>
Link to Vercel:
vercel link --repo --scope <team-slug> -y
Deploy via git push (if you have push access) or CLI deploy.
.vercel/ DirectoryA linked project has either:
.vercel/project.json — from vercel link. Contains projectId and orgId..vercel/repo.json — from vercel link --repo. Contains orgId, remoteName, and a projects map.Not needed when VERCEL_ORG_ID + VERCEL_PROJECT_ID are both set in the environment.
Do NOT run vercel ls, vercel project inspect, or vercel link in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect. Only vercel whoami is safe to run anywhere.
# Set for all environments
echo "value" | vercel env add VAR_NAME --scope <team-slug>
# Set for a specific environment (production, preview, development)
echo "value" | vercel env add VAR_NAME production --scope <team-slug>
# List environment variables
vercel env ls --scope <team-slug>
# Pull env vars to local .env file
vercel env pull --scope <team-slug>
# Remove a variable
vercel env rm VAR_NAME --scope <team-slug> -y
# List recent deployments
vercel ls --format json --scope <team-slug>
# Inspect a specific deployment
vercel inspect <deployment-url>
# View build logs
vercel logs <deployment-url>
# List domains
vercel domains ls --scope <team-slug>
# Add a domain to the project
vercel domains add <domain> --scope <team-slug>
VERCEL_TOKEN as a --token flag. Export it as an environment variable and let the CLI read it natively..env files first..vercel/ files directly. The CLI manages this directory.--format json when structured output will help with follow-up steps.-y on commands that prompt for confirmation to avoid interactive blocking.Check the environment and any .env files present:
printenv | grep -i vercel
grep -i vercel .env 2>/dev/null
If the CLI fails with Authentication required:
vercel whoami (uses VERCEL_TOKEN from environment).Verify the scope is correct:
vercel whoami --scope <team-slug>
Check the build logs:
vercel logs <deployment-url>
Common causes:
package.json is complete and committed.vercel env add.vercel.json. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from package.json; override with vercel.json if detection is wrong.npm install -g vercel
Weekly Installs
3.7K
Repository
GitHub Stars
23.8K
First Seen
7 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex3.4K
opencode3.3K
gemini-cli3.3K
cursor3.3K
github-copilot3.3K
cline3.3K
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装