用最佳 CLI 安全部署 Next.js

---
name: deploy-nextjs-workflow
description: "先本地构建并创建预览，验证通过后再由用户明确批准生产发布。"
---

# 部署 Next.js 应用

## 适用目标

交付可访问的预览和发布报告，不静默修改生产环境。

## 证据边界

- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。

## 推荐工具、安装与认证

- **Vercel CLI**（证据：`docs-verified`，文档检查：`2026-07-10`，未记录独立执行版本）
  - 安装：`npm install --global vercel`
  - 认证：browser login, access token
  - 最小权限：Token 仅授权目标团队和项目，并把生产提升操作单独隔离。
- **Cloudflare Wrangler**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 4.87.0）
  - 安装：`npm install --save-dev wrangler`
  - 认证：OAuth, API token
  - 最小权限：API Token 仅授权任务所需账号、Zone 和 Worker 资源。
- **GitHub CLI**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 2.86.0）
  - 安装：`brew install gh`
  - 认证：OAuth, personal access token, GitHub Actions token
  - 最小权限：使用只读或细粒度 Token，并仅授权任务所需仓库。
- **jq**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 jq-1.7.1-apple）
  - 安装：`brew install jq`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。

## 输入合同

- 仓库路径
- package scripts
- 部署目标
- 最小权限部署凭证

## 输出合同

- 构建结果
- 预览 URL
- 验证记录
- 等待批准的生产命令

## 安全工作流

1. **检查项目** — 读取脚本、框架配置和 Git 状态，再选择部署目标。
   - 输入: 仓库文件和 Git 元数据
   - 输出: 构建命令与部署计划
   - 风险: `read-only`
   - 命令: `jq '.scripts' package.json && git status --short`
2. **构建并创建预览** — 运行项目构建，再用平台 CLI 创建非生产预览。
   - 输入: 构建命令和预览凭证
   - 输出: 预览 URL 和 CLI 日志
   - 风险: `remote-write`
   - 命令: `pnpm build && vercel deploy`
3. **验证后再发布** — 打开预览并检查关键路由，先报告警告，再提出生产发布命令。
   - 输入: 预览 URL 和验收项
   - 输出: 通过/失败报告与生产命令
   - 风险: `read-only`

## 必须先确认

- 在共享账户创建预览
- 执行生产部署
- 修改域名、密钥或环境变量

## 回滚

- 保留上一个生产版本
- 通过平台恢复最近的稳定部署
- 若应用代码有问题则回退发布提交

## 官方来源

- [Vercel CLI documentation](https://vercel.com/docs/cli) — 用于核对当前命令、认证、输出和操作边界。
- [Cloudflare Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/) — 用于核对当前命令、认证、输出和操作边界。
- [GitHub CLI manual](https://cli.github.com/manual/) — 用于核对当前命令、认证、输出和操作边界。