vercel-cli

Vercel CLI 技能

Vercel CLI（vercel 或 vc）从命令行部署、管理和开发 Vercel 平台上的项目。使用 vercel <command> --help 查看任何命令的完整标志详情。

已安装的 CLI 帮助是晦涩或新增标志的权威来源。如果这里的命令示例不够，请先查看 vercel <command> --help，而不是猜测。

仅解析 stdout 中的 URL 和 JSON。警告、进度和 --help 输出到 stderr；仅在搜索帮助文本时合并流。某些帮助命令在打印用法后退出码为 2，因此将打印的用法视为成功的帮助读取。

在 agent/非交互模式下，许多命令将错误和所需确认作为 stdout 上的单个 JSON 对象报告，包含 status、reason、hint 和 next（可运行的后续命令）。优先运行建议的 next 命令，而不是组合重试。读取命令如 list、logs、inspect 和 api 保持其正常输出格式。

关键：项目链接

命令必须从包含 .vercel 文件夹的目录（或其子目录）运行。.vercel 的设置方式取决于项目结构：

• .vercel/project.json：由 vercel link 创建。链接单个项目。适用于单项目仓库，如果只有一个项目，也可以在 monorepo 中工作。
• .vercel/repo.json：由 vercel link --repo 创建。链接可能包含多个项目的仓库。当任何项目具有非根目录（例如 apps/web）时，始终是一个好主意。

从项目子目录（例如 apps/web/）运行会跳过“哪个项目？”提示，因为它是明确的。

当出现问题时，首先检查链接方式——查看 .vercel/ 中的内容以及是 project.json 还是 repo.json。同时使用 vercel whoami 确认你在正确的团队上——在错误的团队上链接是常见错误。

快速开始

npm i -g vercel
vercel login
vercel link              # 单个项目
# 或
vercel link --repo       # monorepo
vercel pull
vercel dev        # 本地开发
vercel deploy     # 预览部署
vercel --prod     # 生产部署

决策树

使用此树路由到正确的参考文件：

• 部署、重新部署、强制构建、无缓存构建或部署源/来源 → references/deployment.md
• 滚动发布、部署钩子、定时任务、缓存、git 连接、Edge Config、重定向、自定义环境 → references/project-infra.md
• 本地开发 → references/local-development.md
• 环境变量 → references/environment-variables.md
• CI/CD 自动化 → references/ci-automation.md
• 域名或 DNS → references/domains-and-dns.md
• 项目或团队 → references/projects-and-teams.md
• 构建失败、部署错误、日志、指标、Speed Insights、Core Web Vitals、活动、性能、预览访问或生产调试 → references/monitoring-and-debugging.md
• 告警、用量、合同、账单购买、令牌、遥测或 CLI 升级 → references/platform-ops.md
• Blob 存储 → references/storage.md
• 容器注册表（vercel vcr：仓库、镜像、标签、docker/podman/buildah 登录、推送/拉取） → references/container-registry.md
• 集成（数据库、存储等） → references/integrations.md
• 连接器（vercel connect） → references/connectors.md
• 路由规则 → references/routing.md
• 防火墙（WAF 规则、IP 封锁、速率限制） → references/firewall.md
• 访问预览部署 → 使用 vercel curl（参见 references/monitoring-and-debugging.md）
• CLI 命令不可用或输出缺少必需字段 → 在一等 CLI 路径不可用或不足时使用 vercel api（参见 references/advanced.md）
• Node.js 后端（Express、Hono 等） → references/node-backends.md
• Monorepos（Turborepo、Nx、workspaces） → references/monorepos.md
• Bun 运行时 → references/bun.md
• 功能标志 → references/flags.md
• 微前端 → references/microfrontends.md
• Sandbox → references/sandbox.md
• Agent、MCP、技能发现或 AI Gateway → references/agent-and-ai.md
• 捕获的请求追踪（vercel traces，包括 --open / --view） → references/advanced.md
• Vercel Apps / OAuth 应用（vercel oauth-apps） → references/advanced.md
• 高级（vercel api 回退、webhooks） → references/advanced.md
• 全局标志 → references/global-options.md
• 首次设置 → references/getting-started.md

反模式

• 在包含多个项目的 monorepo 中使用错误的链接类型：vercel link 创建 project.json，只跟踪一个项目。请改用 vercel link --repo。当出现问题时，首先检查 .vercel/。
• 在 monorepo 中让命令自动链接：如果 .vercel/ 不存在，许多命令会隐式运行 vercel link。这会创建 project.json，可能是错误的。请先显式运行 vercel link（或 --repo）。
• 在错误的团队上链接：使用 vercel whoami 检查，使用 vercel teams switch 切换。
• 在普通 CI 运行中忘记非交互标志：检测到的 agent 默认获得 --non-interactive，但普通 CI 不会——请显式传递它，并且仅对需要确认的命令添加 --yes。
• 在 vercel build 后使用 vercel deploy 而不加 --prebuilt：构建输出会被忽略。
• 使用 vercel redeploy 进行无缓存重建：vercel redeploy 不暴露无缓存标志；当需要不保留构建缓存的全新部署时，使用 vercel deploy --force 而不加 --with-cache。
• 在标志中硬编码令牌：使用 VERCEL_TOKEN 环境变量代替 --token。
• 禁用部署保护：使用 vercel curl 代替以访问预览部署。
• 过早使用 vercel api：当一等 CLI 命令能暴露所需数据或变更时，优先使用它们。