Vercel CLI

You are an expert in the Vercel CLI v50.28.0 (

vercel

or

vc

). The CLI is the primary way to manage Vercel projects from the terminal.

您是Vercel CLI v50.28.0（命令为

vercel

或

vc

）的专家。该CLI是从终端管理Vercel项目的主要方式。

Installation

安装

bash

npm i -g vercel

bash

npm i -g vercel

Login

Core Commands

核心命令

Deployment

部署

bash

undefined

bash

undefined

Preview deployment (from project root)

预览部署（从项目根目录执行）

vercel

Production deployment

生产环境部署

vercel --prod

Build locally, deploy build output only

本地构建，仅部署构建产物

vercel build vercel deploy --prebuilt

Build for production (uses production env vars)

为生产环境构建（使用生产环境变量）

vercel build --prod vercel deploy --prebuilt --prod

Force a new deployment (skip cache)

强制全新部署（跳过缓存）

vercel --force

Promote a preview deployment to production

将预览部署升级为生产环境部署

vercel promote <deployment-url>

Rollback to previous production deployment

回滚到上一个生产环境部署版本

vercel rollback

undefined

vercel rollback

undefined

Development

开发

bash

undefined

bash

undefined

Start local dev server with Vercel features

启动带有Vercel特性的本地开发服务器

vercel dev

Link current directory to a Vercel project

将当前目录关联到一个Vercel项目

vercel link

Deterministic non-interactive link (recommended for bootstrap/automation)

确定性非交互式关联（推荐用于初始化/自动化场景）

vercel link --yes --project <name-or-id> --scope <team>

Pull environment variables and project settings

拉取环境变量和项目设置

vercel pull

Pull specific environment

拉取指定环境的配置

vercel pull --environment=production

Open linked project in the Vercel Dashboard

在Vercel控制台中打开关联的项目

vercel open

undefined

vercel open

undefined

Deterministic Project Linking (Recommended)

确定性项目关联（推荐）

Prefer explicit non-interactive linking for bootstrap and automation:

bash

vercel link --yes --project <name-or-id> --scope <team>

This is more reliable than interactive prompt-driven linking, which can pick the wrong project or team in multi-account setups. If there is any ambiguity, run

vercel open

to confirm the dashboard project, then relink with explicit

--project

and

--scope

.

对于初始化和自动化场景，优先使用显式的非交互式关联方式：

bash

vercel link --yes --project <name-or-id> --scope <team>

这种方式比交互式提示关联更可靠，在多账户环境中，交互式方式可能会关联到错误的项目或团队。如果存在歧义，可运行

vercel open

确认控制台中的项目，然后使用显式的

--project

和

--scope

参数重新关联。

Environment Variables

环境变量

bash

undefined

bash

undefined

List all environment variables

列出所有环境变量

vercel env ls

Add an environment variable

添加一个环境变量

vercel env add MY_VAR

Add for specific environments

为指定环境添加变量

vercel env add MY_VAR production vercel env add MY_VAR preview development

Add branch-scoped variable

添加分支专属变量

vercel env add MY_VAR preview --branch=feature-x

Add sensitive (write-only) variable

添加敏感（仅可写入）变量

vercel env add MY_SECRET --sensitive

Remove an environment variable

删除一个环境变量

vercel env rm MY_VAR

Pull all env vars to .env.local

拉取所有环境变量到.env.local

vercel env pull vercel env pull .env.production.local --environment=production

undefined

vercel env pull vercel env pull .env.production.local --environment=production

undefined

Logs & Inspection

日志与检查

The

vercel logs

command (rebuilt February 2026) supports historical log querying and uses git context by default — it automatically scopes logs to your current repository when run from a project directory.

bash

undefined

vercel logs

命令（2026年2月重构）支持历史日志查询，默认使用Git上下文——在项目目录中运行时，会自动将日志范围限定到当前仓库。

bash

undefined

View runtime/function logs (real-time)

查看运行时/函数日志（实时）

vercel logs <deployment-url>

Follow logs in real-time (streaming mode)

实时跟踪日志（流模式）

vercel logs <deployment-url> --follow

Query historical logs (no longer limited to live-only)

查询历史日志（不再局限于实时日志）

vercel logs --since 24h vercel logs --since 7d

Filter by time range

按时间范围过滤

vercel logs <deployment-url> --since 1h vercel logs <deployment-url> --since 30m

Filter by log level

按日志级别过滤

vercel logs <deployment-url> --level error vercel logs <deployment-url> --level warning

Filter by deployment ID, request ID, or arbitrary string

按部署ID、请求ID或任意字符串过滤

vercel logs --deployment-id dpl_xxxxx vercel logs --request-id req_xxxxx vercel logs --query "TypeError"

Output as JSON (for piping to jq or other tools)

以JSON格式输出（用于管道传输到jq或其他工具）

vercel logs <deployment-url> --json

Combine filters: stream errors from the last hour as JSON

组合过滤：以JSON格式流式传输最近1小时的错误日志

vercel logs <deployment-url> --follow --since 1h --level error --json

Inspect a deployment (build details, metadata, function list)

检查部署详情（构建信息、元数据、函数列表）

vercel inspect <deployment-url>

List recent deployments

列出最近的部署记录

vercel ls


> **Note:** `vercel logs` shows runtime request logs only. For build output, use
> `vercel inspect <deployment-url>` or view build logs at `https://vercel.com/{team}/{project}/deployments` → select deployment → **Build Logs**.
>
> **Drains and advanced observability:** Log drains, trace export, and analytics data forwarding are
> configured via the Vercel Dashboard at `https://vercel.com/dashboard/{team}/~/settings/log-drains` or REST API (`/v1/drains`), not the CLI. See `⤳ skill: observability`
> for drain setup, payload schemas, and signature verification.

vercel ls


> **注意**：`vercel logs`仅显示运行时请求日志。如需查看构建输出，请使用`vercel inspect <deployment-url>`，或访问`https://vercel.com/{team}/{project}/deployments` → 选择对应部署 → **构建日志**。
>
> **日志导出与高级可观测性**：日志导出、追踪数据导出和分析数据转发需通过Vercel控制台的`https://vercel.com/dashboard/{team}/~/settings/log-drains`或REST API（`/v1/drains`）配置，CLI不支持该操作。如需了解导出设置、负载架构和签名验证，请查看`⤳ skill: observability`。

Domains

域名

bash

undefined

bash

undefined

List domains

列出域名

vercel domains ls

Add a domain to a project

为项目添加域名

vercel domains add example.com

Remove a domain

删除域名

vercel domains rm example.com

undefined

vercel domains rm example.com

undefined

DNS

bash

undefined

bash

undefined

List DNS records

列出DNS记录

vercel dns ls example.com

Add a DNS record

添加DNS记录

vercel dns add example.com @ A 1.2.3.4

undefined

vercel dns add example.com @ A 1.2.3.4

undefined

Teams

团队

bash

undefined

bash

undefined

List teams

列出团队

vercel teams ls

Switch to a team

切换到指定团队

vercel teams switch my-team

undefined

vercel teams switch my-team

undefined

Cache Management

缓存管理

bash

undefined

bash

undefined

Purge all cache (CDN + Data cache) for current project

清除当前项目的所有缓存（CDN + 数据缓存）

vercel cache purge

Purge only CDN cache

仅清除CDN缓存

vercel cache purge --type cdn

Purge only Data cache

仅清除数据缓存

vercel cache purge --type data

Purge without confirmation prompt

无需确认提示直接清除缓存

vercel cache purge --yes

Invalidate by tag (stale-while-revalidate)

按标签使缓存失效（采用stale-while-revalidate策略）

vercel cache invalidate --tag blog-posts

Invalidate multiple tags

使多个标签的缓存失效

vercel cache invalidate --tag blog-posts,user-profiles,homepage

Hard delete by tag (blocks until revalidated — use with caution)

按标签强制删除缓存（会阻塞直到重新验证——谨慎使用）

vercel cache dangerously-delete --tag blog-posts

Hard delete with revalidation deadline (deletes only if not accessed within N seconds)

设置重新验证期限的强制删除（仅删除N秒内未访问的缓存）

vercel cache dangerously-delete --tag blog-posts --revalidation-deadline-seconds 3600

Invalidate cached image transformations by source path

按源路径使图片转换缓存失效

vercel cache invalidate --srcimg /api/avatar/1

Hard delete cached image transformations

强制删除图片转换缓存

vercel cache dangerously-delete --srcimg /api/avatar/1


**Key distinction:** `invalidate` serves STALE and revalidates in the background. `dangerously-delete` serves MISS and blocks while revalidating. Prefer `invalidate` unless you need immediate freshness.

**Note:** `--tag` and `--srcimg` cannot be used together.

vercel cache dangerously-delete --srcimg /api/avatar/1


**核心区别**：`invalidate`会返回过期内容并在后台重新验证缓存。`dangerously-delete`会返回未命中状态并在重新验证完成前阻塞请求。除非需要立即获取最新内容，否则优先使用`invalidate`。

**注意**：`--tag`和`--srcimg`参数不能同时使用。

MCP Server Integration

MCP服务器集成

bash

undefined

bash

undefined

Initialize global MCP client configuration for your Vercel account

为您的Vercel账户初始化全局MCP客户端配置

vercel mcp

Set up project-specific MCP access for the linked project

为已关联的项目配置专属MCP访问权限

vercel mcp --project


The `vercel mcp` command links your local MCP client configuration to a Vercel Project. It generates connection details so AI agents and tools can call your MCP endpoints deployed on Vercel securely.

vercel mcp --project


`vercel mcp`命令可将本地MCP客户端配置关联到Vercel项目，生成的连接信息可让AI Agent和工具安全调用部署在Vercel上的MCP端点。

Programmatic Configuration (

@vercel/config

)

程序化配置（

@vercel/config

）

bash

undefined

bash

undefined

Compile vercel.ts to JSON (stdout)

将vercel.ts编译为JSON（输出到标准输出）

npx @vercel/config compile

Validate configuration and show summary

验证配置并显示摘要

npx @vercel/config validate

Generate vercel.json locally for development

生成本地开发用的vercel.json

npx @vercel/config generate


Use `vercel.ts` (or `.js`, `.mjs`, `.cjs`, `.mts`) instead of `vercel.json` for type-safe, dynamic project configuration. Only one config file per project — `vercel.json` or `vercel.ts`, not both.

> **Note:** Legacy `now.json` support will be removed on March 31, 2026. Rename to `vercel.json` (no content changes needed).

npx @vercel/config generate


建议使用`vercel.ts`（或`.js`、`.mjs`、`.cjs`、`.mts`）替代`vercel.json`，以实现类型安全的动态项目配置。每个项目只能存在一个配置文件——要么是`vercel.json`，要么是`vercel.ts`，不能同时存在。

> **注意**：旧版`now.json`的支持将在2026年3月31日终止。只需将文件重命名为`vercel.json`即可（无需修改内容）。

Marketplace Integrations

市场集成

Auto-provisioning is the default for

vercel integration add

— the CLI automatically creates resources and sets environment variables without extra prompts.

bash

undefined

vercel integration add

默认采用自动配置模式——CLI会自动创建资源并设置环境变量，无需额外交互。

bash

undefined

List installed integrations

列出已安装的集成

vercel integration list

Add an integration (auto-provisions env vars by default)

添加集成（默认自动配置环境变量）

vercel integration add neon

Open an integration's dashboard

打开集成的控制台

vercel integration open neon

Remove an integration

删除集成

vercel integration remove neon

undefined

vercel integration remove neon

undefined

Agent-Optimized:

discover

and

guide

针对Agent优化的

discover

和

guide

命令

AI agents can autonomously discover, install, and retrieve setup instructions for Marketplace integrations (added March 2026):

bash

undefined

AI Agent可自主发现、安装并获取市场集成的设置指南（2026年3月新增）：

bash

undefined

Search the integration catalog (returns JSON for automation)

搜索集成目录（返回JSON格式结果，适用于自动化场景）

vercel integration discover --format=json

Search with a keyword filter

按关键词筛选搜索

vercel integration discover database --format=json

Get agent-friendly setup guide with code snippets

获取适合Agent的设置指南及代码片段

vercel integration guide neon

Full workflow: discover → add → guide

完整工作流：发现 → 添加 → 查看指南

vercel integration discover storage --format=json vercel integration add neon vercel integration guide neon


- `discover` — Searches the Vercel Marketplace catalog. Use `--format=json` for non-interactive output suitable for scripting and agent pipelines.
- `guide <name>` — Returns getting-started documentation in agent-friendly markdown: environment variables, SDK setup, and code snippets.
- Human-in-the-loop safety: the CLI prompts for developer confirmation when accepting Terms of Service.

> Full subcommands: `discover`, `guide`, `add`, `list` (alias `ls`), `balance`, `open`, `remove`.

vercel integration discover storage --format=json vercel integration add neon vercel integration guide neon


- `discover` —— 搜索Vercel市场集成目录。使用`--format=json`可获取非交互式输出，适用于脚本和Agent流水线。
- `guide <name>` —— 返回适合Agent的Markdown格式快速入门文档，包含环境变量、SDK设置和代码片段。
- 人工审核安全机制：当接受服务条款时，CLI会提示开发者进行确认。

> 完整子命令：`discover`、`guide`、`add`、`list`（别名`ls`）、`balance`、`open`、`remove`。

Project-Level Routing (No Redeploy)

项目级路由（无需重新部署）

Create and update routing rules — headers, rewrites, redirects — without building a new deployment. Rules take effect instantly.

Available via dashboard (CDN tab), API, CLI, and Vercel SDK. Project-level routes run after bulk redirects and before deployment config routes.

创建和更新路由规则——请求头、重写、重定向——无需构建新的部署包。规则会立即生效。

该功能可通过控制台（CDN标签页）、API、CLI和Vercel SDK使用。项目级路由会在批量重定向之后、部署配置路由之前执行。

Feature Flags

功能标志

bash

undefined

bash

undefined

Create a feature flag

创建功能标志

vercel flags add redesigned-checkout --kind boolean --description "New checkout flow"

List SDK keys

列出SDK密钥

vercel flags sdk-keys ls

Enable/disable, archive, and manage flags from CLI

从CLI启用/禁用、归档及管理功能标志

vercel flags --help


See `⤳ skill: vercel-flags` for full flag configuration and adapter patterns.

vercel flags --help


如需了解完整的功能标志配置和适配模式，请查看`⤳ skill: vercel-flags`。

Direct API Access

直接API访问

The

vercel api

command (added January 2026) gives direct access to the full Vercel REST API from the terminal. Designed for AI agents — Claude Code can call Vercel APIs with no additional configuration.

bash

undefined

vercel api

命令（2026年1月新增）允许从终端直接访问完整的Vercel REST API。专为AI Agent设计——Claude Code可直接调用Vercel API，无需额外配置。

bash

undefined

Call any Vercel REST API endpoint

调用任意Vercel REST API端点

vercel api GET /v9/projects vercel api GET /v13/deployments vercel api POST /v9/projects/:id/env --body '{"key":"MY_VAR","value":"val","target":["production"]}'

Pipe JSON output to jq

将JSON输出通过管道传输到jq

vercel api GET /v9/projects | jq '.[].name'

undefined

vercel api GET /v9/projects | jq '.[].name'

undefined

Metrics

指标

bash

undefined

bash

undefined

Query project metrics (rich text output with sparklines)

查询项目指标（带迷你折线图的富文本输出）

vercel metrics

Raw values for scripting

用于脚本的原始数值输出

vercel metrics --raw-values

undefined

vercel metrics --raw-values

undefined

CI/CD Integration

CI/CD集成

Required environment variables for CI:

bash

VERCEL_TOKEN=<your-token>
VERCEL_ORG_ID=<org-id>
VERCEL_PROJECT_ID=<project-id>

CI环境所需的环境变量：

bash

VERCEL_TOKEN=<your-token>
VERCEL_ORG_ID=<org-id>
VERCEL_PROJECT_ID=<project-id>

GitHub Actions Example

GitHub Actions示例

yaml

- name: Deploy to Vercel
  run: |
    vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
    vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
    vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

yaml

- name: 部署到Vercel
  run: |
    vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
    vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
    vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

Global Options

全局选项

Flag	Purpose
`--token`	Authentication token (for CI)
`--cwd <dir>`	Working directory
`--debug` / `-d`	Verbose output
`--yes` / `-y`	Skip confirmation prompts
`--scope <team>`	Execute as a team

参数	用途
`--token`	身份验证令牌（用于CI环境）
`--cwd <dir>`	指定工作目录
`--debug` / `-d`	输出详细日志
`--yes` / `-y`	跳过确认提示
`--scope <team>`	以指定团队身份执行命令

Common Workflows

常见工作流

First-Time Setup

首次设置

bash

vercel link          # Connect to Vercel project
vercel env pull      # Get environment variables
vercel dev           # Start local dev

bash

vercel link          # 关联到Vercel项目
vercel env pull      # 获取环境变量
vercel dev           # 启动本地开发服务器

Deploy from CI

从CI环境部署

bash

vercel pull --yes --environment=production --token=$TOKEN
vercel build --prod --token=$TOKEN
vercel deploy --prebuilt --prod --token=$TOKEN

bash

vercel pull --yes --environment=production --token=$TOKEN
vercel build --prod --token=$TOKEN
vercel deploy --prebuilt --prod --token=$TOKEN

Quick Preview

快速预览部署

bash

vercel               # Creates preview deployment, returns URL

bash

vercel               # 创建预览部署并返回URL

vercel-cli

Original

Translation

Vercel CLI

Vercel CLI

Installation

安装

Login

登录

Core Commands

核心命令

Deployment

部署

Preview deployment (from project root)

预览部署（从项目根目录执行）

Production deployment

生产环境部署

Build locally, deploy build output only

本地构建，仅部署构建产物

Build for production (uses production env vars)

为生产环境构建（使用生产环境变量）

Force a new deployment (skip cache)

强制全新部署（跳过缓存）

Promote a preview deployment to production

将预览部署升级为生产环境部署

Rollback to previous production deployment

回滚到上一个生产环境部署版本

Development

开发

Start local dev server with Vercel features

启动带有Vercel特性的本地开发服务器

Link current directory to a Vercel project

将当前目录关联到一个Vercel项目

Deterministic non-interactive link (recommended for bootstrap/automation)

确定性非交互式关联（推荐用于初始化/自动化场景）

Pull environment variables and project settings

拉取环境变量和项目设置

Pull specific environment

拉取指定环境的配置

Open linked project in the Vercel Dashboard

在Vercel控制台中打开关联的项目

Deterministic Project Linking (Recommended)

确定性项目关联（推荐）

Environment Variables

环境变量

List all environment variables

列出所有环境变量

Add an environment variable

添加一个环境变量

Add for specific environments

为指定环境添加变量

Add branch-scoped variable

添加分支专属变量

Add sensitive (write-only) variable

添加敏感（仅可写入）变量

Remove an environment variable

删除一个环境变量

Pull all env vars to .env.local

拉取所有环境变量到.env.local

Logs & Inspection

日志与检查

View runtime/function logs (real-time)

查看运行时/函数日志（实时）

Follow logs in real-time (streaming mode)

实时跟踪日志（流模式）

Query historical logs (no longer limited to live-only)

查询历史日志（不再局限于实时日志）

Filter by time range

按时间范围过滤

Filter by log level

按日志级别过滤

Filter by deployment ID, request ID, or arbitrary string

按部署ID、请求ID或任意字符串过滤

Output as JSON (for piping to jq or other tools)

以JSON格式输出（用于管道传输到jq或其他工具）

Combine filters: stream errors from the last hour as JSON

组合过滤：以JSON格式流式传输最近1小时的错误日志

Inspect a deployment (build details, metadata, function list)

检查部署详情（构建信息、元数据、函数列表）

List recent deployments

Programmatic Configuration (
`@vercel/config`
)

程序化配置（
`@vercel/config`
）

Agent-Optimized:
`discover`
and
`guide`

针对Agent优化的
`discover`
和
`guide`
命令