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 project inspect --non-interactive，并确认报告的所有者和项目。此命令在非交互模式下只解析现有上下文；如果出现 link_required 或目标不匹配，请停止操作，不要自动创建链接。

许多项目感知命令也接受 --project <name-or-id> 和 --scope <team>，用于显式指定单次命令的目标。使用前，请确认该目标和范围符合用户的预期。

• <cwd>/.vercel/project.json：由 vercel link 创建。此精确工作目录中的链接优先于仓库链接。CLI 通常不会在任意子目录中运行时继承根目录的 project.json。
• <repo-root>/.vercel/repo.json：由 vercel link --repo 创建。CLI 会选择包含当前工作目录的最深层项目目录。
• 不匹配的仓库路径：如果没有仓库映射包含当前工作目录，交互式仓库解析会提示用户从已配置项目中选择。非交互式仓库解析目前会选择唯一已配置的项目；如果有多个选项，则保持未解析状态。随后，设置项目的命令可能会进入链接流程，因此非交互模式通常不能确保失败时不产生影响。

位于应用目录中并不能证明已选中预期项目。请显式检查解析出的项目，尤其是在仓库映射未涵盖该目录时。

vercel whoami --format json 可识别已验证身份的用户和当前生效的团队；纯非 TTY 环境下的 vercel whoami 只会输出用户名。两者都不会验证已链接的项目。只读项目命令仍可能要求登录或重新进行团队 SAML 身份验证，并打开浏览器／设备验证流程。请让用户先主动完成该流程，再继续操作。

快速入门

npm i -g vercel
vercel login
vercel link              # single project
# OR
vercel link --repo       # monorepo
vercel pull
vercel dev        # local development
vercel deploy     # preview deployment
vercel --prod     # production deployment

决策树

使用此树跳转到正确的参考文件：

• 部署、重新部署、强制构建、无缓存构建或部署来源／溯源 → 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
• Vercel Toolbar 评论（vercel comments） → references/comments.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
• 单体仓库（Turborepo、Nx、工作区） → references/monorepos.md
• Bun 运行时 → references/bun.md
• 功能标志（vercel flags：创建、检查、设置、拆分、逐步推出、规则、细分、sdk-keys） → 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 api 后备方案、Webhook） → references/advanced.md
• 全局标志 → references/global-options.md
• 首次设置 → references/getting-started.md

反模式

• 在包含多个项目的单体仓库中使用错误的链接类型：vercel link 会创建 project.json，该文件只能跟踪一个项目。请改用 vercel link --repo。出现问题时，先检查 .vercel/。
• 在单体仓库中让命令自动建立链接：许多命令会在 .vercel/ 不存在时隐式运行 vercel link。这会创建 project.json，可能并不适用。请先显式运行 vercel link（或 --repo）。
• 假设应用子目录决定项目：使用 vercel project inspect --non-interactive 进行验证；目前在非交互模式下，如果仓库路径不匹配，可能会回退到唯一配置的项目。
• 使用 vercel whoami 验证已链接的项目：vercel whoami --format json 会报告身份验证和团队上下文，而不是所选项目。
• 在普通 CI 运行中忘记添加非交互标志：检测到的 Agent 默认会使用 --non-interactive，但普通 CI 不会——请在普通 CI 中显式传入该标志，并仅在需要确认的命令中添加 --yes。
• 在 vercel build 后不带 --prebuilt 使用 vercel deploy：构建输出会被忽略。
• 使用 vercel redeploy 进行无缓存重建：vercel redeploy 不提供无缓存标志；需要全新部署且不保留构建缓存时，请使用 vercel deploy --force，不要使用 --with-cache。
• 在标志中硬编码令牌：请使用 VERCEL_TOKEN 环境变量，而不是 --token。
• 禁用部署保护：请改用 vercel curl 访问预览部署。
• 过早使用 vercel api：如果 CLI 提供了所需数据或修改操作，请优先使用内置的 CLI 命令。