用途：在 GitHub Actions 中自动化 Vercel 部署，实现 PR 预览部署、合并 main 后的生产部署，以及可选的测试门禁。适用于需要自动化部署、配置预览机器人或自定义 CI 流水线的场景。
前置条件：启用 Actions 的 GitHub 仓库；已关联该仓库的 Vercel 项目；将 VERCEL_TOKEN 存为 GitHub Secret；从 .vercel/project.json 获取 VERCEL_ORG_ID 与 VERCEL_PROJECT_ID。
主要能力与用法：
- 写入密钥：cat .vercel/project.json 读取 orgId、projectId，再用 gh secret set VERCEL_TOKEN --body "your-vercel-token" 等命令写入仓库 Secret。
- PR 预览：工作流在 pull_request 到 main 时触发，安装 vercel@latest，执行 vercel pull --yes --environment=preview，vercel build，vercel deploy --prebuilt 取得预览 URL，并用 actions/github-script 将 URL 评论到 PR。
- 生产部署：在 push 到 main 时触发，执行 vercel pull --yes --environment=production，vercel build --prod，再 vercel deploy --prebuilt --prod。
- 测试门禁：deploy 任务用 needs: test 依赖测试任务，先运行 npm ci、npm test、npm run lint、npx tsc --noEmit，通过后才部署。
- 跳过非代码改动的构建：在 vercel.json 配置 ignoreCommand，例如 git diff HEAD^ HEAD --quiet -- . ':!docs' ':!*.md' ':!.github'，或在面板 Settings > Git > Ignored Build Step 设置。
- 内置 Git 集成替代方案：在 Vercel 面板连接 GitHub 仓库后自动部署，推送生成预览、合并 main 生成生产，可在 Settings > Git 配置生产分支、预览分支与自定义域名自动分配；该方式无需 CI 配置，但测试门禁控制更弱。
输出：每个 PR 的预览部署并在 PR 中评论 URL；合并 main 且测试通过后的生产部署；防止坏代码进入生产的测试门禁；仅文档改动的构建跳过规则。
错误处理：提示 VERCEL_TOKEN is not set 表示未配置密钥；Could not find project 需检查 ORG_ID/PROJECT_ID；vercel pull 失败可能是令牌权限不足；PR 无预览评论需加入 actions/github-script；构建缓存失效可对 node_modules 与 .vercel/output 使用 actions/cache。
限制：资料未提供收费、价格、平台可用性、性能效果或完整使用步骤之外的内容；相关数值与配置以实际项目为准。