vercel-deploy

Vercel 部署

当任务是专门在 Vercel 上操作部署，而不是设计通用发布策略时，使用此技能。

vercel-deploy 是针对特定提供商的入口，可用于：

• 创建或刷新 Vercel 预览部署
• 在 Vercel 上直接进行生产部署
• 暂存部署、验证后再将其提升为正式版本
• 分配稳定的预览别名或绑定自定义域名
• 检查并修复 Vercel 环境变量作用域及重新部署需求
• 在生产部署出现问题时，执行以回滚为导向的检查

选择模式前，请阅读以下支持文档：

• references/modes-and-boundaries.md
• references/preview-production-command-packets.md
• references/env-domain-rollback-troubleshooting.md

何时使用此技能

• 用户明确要求在 Vercel 上部署项目
• 任务涉及 Vercel 预览 URL、预览别名或稳定的演示环境
• 已有关联的 Vercel 部署，需要将其提升为正式版本或处理回滚
• 主要问题是 Vercel 环境变量作用域、Vercel 域名/别名状态，或 Vercel 特定的发布验证
• 已选定提供商，用户需要 Vercel 运维指导，而非与厂商无关的发布设计

何时不使用此技能

• 主要问题是通用发布策略、发布门禁、金丝雀策略或跨提供商部署设计 → 使用 deployment-automation
• 主要任务是围绕部署流程编辑 GitHub Actions / CI YAML / 任务运行器 → 使用 deployment-automation
• 主要任务是安装 Node、Vercel CLI、初始化身份验证或关联本地机器 → 使用 system-environment-setup
• 部署流程本身尚未正常工作，应用/框架/构建就已出错 → 首先使用 debugging 或相关的框架/构建技能
• 主要任务是发布后的长期遥测、SLO 或告警 → 使用 monitoring-observability

说明

第 1 步：将 Vercel 任务归纳为一个方案

在使用命令前，准确选择一种主要模式。

vercel_packet:
  primary_mode: preview-deploy | production-deploy | promote-preview | alias-domain | env-sync | rollback-response
  project_state: linked | unlinked | unknown
  build_mode: source-build | prebuilt | unknown
  target_environment: preview | production | development | custom | unknown
  url_goal: generated-url | stable-preview-alias | custom-domain | mixed | none
  verification_depth: none | smoke | health-plus-logs | release-checklist

主要模式：

• preview-deploy — 创建或刷新可供测试的 Vercel 预览
• production-deploy — 直接进行全新的生产部署
• promote-preview — 验证现有部署，然后将其设为当前版本
• alias-domain — 应用/验证稳定的预览别名或自定义域名
• env-sync — 修复环境变量作用域或过期的本地/项目环境状态
• rollback-response — 将生产环境回退到已知正常的部署，并验证恢复情况

如果请求包含多个目标，选择最先需要回答的目标，并明确说明其余目标的处理方式。

第 2 步：仅收集最少且真实的证据

不要仅凭框架名称猜测。先确认最少的一组可靠信息：

1. 项目是否已关联 Vercel（vercel link、.vercel/project.json 或控制面板证据）？
2. 目标是否确实是预览、生产，还是自定义/开发环境？
3. 部署流程是基于源代码还是基于预构建产物？
4. 用户关注的是生成的部署 URL、稳定别名，还是自定义域名？
5. 这确实是部署/切换问题，还是仍需重新部署的环境变量/配置不匹配问题？
6. 需要什么验证证据：仅 URL、冒烟检查、健康状态与日志、DNS 验证，还是回滚验证？

如果有任何一项未知，请说明假设，不要假装已完全确定模式。

第 3 步：使用匹配的运维路径

不要一次性列出所有命令。选择与该模式匹配的参考方案。

A. preview-deploy

在交付内容是可测试的预览部署时使用。

• 优先使用已关联项目的 CLI 或由仪表板支持的预览流程。
• 返回生成的部署 URL，以及任何稳定别名方案。
• 如果目标是稳定的演示 URL，请将结果交给 alias-domain 处理，而不是把所有内容混在一起。

使用数据包：references/preview-production-command-packets.md#preview-deploy-packet

B. production-deploy

在用户明确要求立即进行新的生产部署时使用。

• 说明部署是从源代码构建，还是使用预构建产物。
• 报告实际到达的生产 URL／域名。
• 将部署成功与部署后验证分开说明。

使用数据包：references/preview-production-command-packets.md#direct-production-deploy-packet

C. promote-preview

在部署已存在，且任务是安全地切换时使用。

• 在升级前验证确切的部署 URL／提交。
• 将升级视为发布操作，而不是神奇地切换指针。
• 在相关时说明团队范围或域名方面的注意事项。
• 将生产环境验证结果与升级命令本身分开报告。

使用数据包：references/preview-production-command-packets.md#staged-production--promote-packet

D. alias-domain

在稳定 URL 是实际交付内容时使用。

• 区分生成的 URL、稳定的预览别名和生产自定义域名。
• 将 DNS／手动验证状态与 CLI 成功状态分开报告。
• 保留原始部署 URL，作为备用证据。

使用数据包：references/env-domain-rollback-troubleshooting.md#aliases-and-domains

E. env-sync

在预览环境与生产环境的行为因变量缺失、过期或作用范围不正确而不同时使用。

• 先检查目标环境。
• 指出环境变量更改适用于新部署，不会影响旧部署。
• 区分 Vercel 环境范围与应用级规范 URL／配置要求。

使用数据包：references/env-domain-rollback-troubleshooting.md#environment-variables

F. rollback-response

在必须快速恢复生产流量时使用。

• 确认当前有问题的部署以及确切的回滚目标。
• 在声称已恢复之前，指出配置过期／定时任务／计划限制方面的注意事项。
• 回滚后重新检查生产日志／健康状况。

使用数据包：references/env-domain-rollback-troubleshooting.md#rollback

第 4 步：回答时明确职责边界

当请求偏离主题时，使用此分流表。

如果请求听起来像……	使用
“设计跨服务商的发布门禁、金丝雀策略或回滚策略”	deployment-automation
“重写运行 Vercel 命令的 GitHub Actions 工作流”	deployment-automation
“安装 Vercel CLI、身份验证、Node，或关联本地凭据”	system-environment-setup
“部署成功前构建就崩溃了”	debugging 或特定框架的技能
“设置仪表板、告警或长期的发布后监控”	monitoring-observability
“在 Vercel 上检查、部署、升级、设置别名、管理域名、同步环境变量或回滚”	vercel-deploy

第 5 步：仅在环境明确依赖旧版可认领部署助手时提及它

此目录仍包含 scripts/deploy.sh，这是一个可认领预览助手，可打包 tarball 并返回预览／认领 URL。请将其视为特定环境的旧版快捷方式，而非默认的 Vercel 操作模式。

仅在以下条件全部满足时使用：

• 运行环境明确要求可认领部署端点
• 任务仅是创建可认领的预览 URL
• 已关联项目、升级、别名／域名、环境变量同步和回滚操作均不在范围内

否则，请优先采用上文所述的官方 Vercel CLI／仪表板模式。

输出格式

返回特定模式的数据包，而不是零散的命令集合。

最低限度的结构：

# Vercel Operation Summary
- Mode:
- Project linked:
- Build mode:
- Target environment:
- URL / deployment:
- Verification performed:
- Remaining risk or manual step:
- Routed-out work (if any):

示例

示例 1：使用稳定别名预览部署

用户询问：“将这个 Next.js 分支部署到 Vercel，并给我一个稳定的预览 URL。”

预期操作：

• 选择 preview-deploy 作为主要模式
• 通过预览数据包进行部署
• 获取生成的部署 URL
• 单独设置或规划稳定别名
• 返回两个 URL，以及仍需完成的 DNS／手动步骤

示例 2：提升已验证的暂存部署

用户询问：“这个 Vercel 构建已经通过 QA。将它提升到生产环境并进行验证。”

预期操作：

• 选择 promote-preview 作为主要模式
• 首先验证确切的部署／提交
• 执行暂存环境到生产环境的提升数据包
• 报告提升后的生产验证结果
• 适用时说明范围／域名方面的注意事项

示例 3：部署中无法读取 Vercel 环境变量

用户询问：“Vercel 中有这个变量，但部署无法读取它。”

预期操作：

• 选择 env-sync
• 验证预期的环境范围
• 确认环境变量变更后是否进行了新部署
• 使用 Vercel 环境变量检查／拉取来核实可信状态
• 指出应用层仍需设置的规范 URL／配置

示例 4：将通用发布设计交由其他流程处理

用户询问：“帮我们设计跨服务提供商的暂存到生产发布策略和金丝雀规则。”

预期操作：

• 不要假装这只是 Vercel 专属操作
• 将主要任务交由 deployment-automation
• 仅将明确针对 Vercel 的后续操作保留在 vercel-deploy 中

最佳实践

1. 给出命令前，先选择一种主要的 Vercel 模式。
2. 优先使用已关联项目的官方 CLI／控制面板流程，而非过时的 tarball 快捷方式。
3. 将部署、提升、别名／域名、环境变量修复和回滚视为不同的操作数据包。
4. 始终区分生成的部署 URL、稳定的预览别名和自定义域名。
5. 记住，环境变量变更只会影响新部署。
6. 不要夸大 vercel promote 或回滚的无损程度；应说明范围／域名／计划／配置方面的注意事项。
7. 将通用发布设计交回 deployment-automation，以避免职责重叠。

参考资料

• 通过 Vercel CLI 部署项目
• vercel deploy
• vercel promote
• vercel rollback
• 环境变量
• 系统环境变量
• 使用域名
• 使用 Vercel 部署 Git 仓库