Biz Deploy Vercel — 一键安全部署网站到 Vercel
此技能能将 本地项目目录（React / Next.js / Vite / 静态 HTML）转换为 Vercel 上的在线 URL，并附带 SSL、CDN 和预览部署。目标：让独立开发者 / 中小企业无需了解 DevOps 知识，仅通过与 Claude 的对话即可部署落地页。
核心理念: 不询问那些 Claude 可以自行检查的信息。自动检测框架，自动生成
vercel.json，仅在遇到真正的 手动环节（浏览器登录、自定义域名 DNS）时暂停。
何时使用
用户希望:
- 将落地页/网站推送到在线 URL 进行分享/测试/广告投放
- 修改代码后重新部署项目
- 为新仓库首次设置 Vercel
- 配置自定义域名指向 Vercel
何时不应使用
- 仅需本地构建，暂不公开 → 跳过，使用
npm run build/next dev。 - 需要部署到 Netlify / Cloudflare Pages / AWS → 此技能专用于 Vercel。
- 需要复杂的 CI/CD（如自定义 GitHub Actions） → 仍可用此技能初始化项目，但工作流由用户自行配置。
- 需要全状态后端 Node.js（WebSocket、长轮询） → Vercel serverless 不适用，请使用 Railway / Fly.io。
用户将获得的结果
- Live URL 形式如
https://<project>.vercel.app（生产）或预览 URL。 - Inspect URL 形式如
https://vercel.com/<account>/<project>/<deployment-id>，用于查看日志。 - 项目链接信息 存储在
.vercel/project.json（已被 .gitignore 忽略） — 下次部署只需运行vercel --prod。 - 如果用户要求自定义域名 → 提供具体的 DNS 配置说明（A 记录 / CNAME）。
6 步工作流
第一步 — 预检：检查 Vercel CLI / MCP
运行 scripts/check_vercel.sh（或内联等效命令）来确定以下三项的状态：
| 检查项 | 命令 | 预期结果 |
|---|---|---|
| Node.js | node --version | v18+ 或 v20+ |
| Vercel CLI | vercel --version | 返回版本号（v32+） |
| Vercel 认证 | vercel whoami | 返回用户名 |
若缺少 Node.js:
- macOS: 建议
brew install node或下载 https://nodejs.org - Windows: 指导从 https://nodejs.org/en/download/ 下载 .msi 安装程序
- Linux: 使用
nvm install --lts或包管理器 - 暂停技能，等待用户安装完成后通知。
若缺少 Vercel CLI:
- 检测当前使用的包管理器（按优先级检查
pnpm、yarn、npm，或读取项目的 lockfile）。 - 全局安装:
pnpm add -g vercel（如果用户使用 pnpm）npm install -g vercel（默认）
- 通过
vercel --version再次验证。
若已安装 Vercel CLI 但未认证（vercel whoami 报错）:
- 运行
vercel login— 此命令会打开浏览器，用户需点击确认。这是一个手动环节，无法跳过。 - 通知用户: “我已经运行了
vercel login。请打开浏览器，点击确认以完成身份验证。完成后，输入 'ok' 让我继续。” - 暂停，等待用户反馈。
如果用户表示已配置 Vercel MCP:
- 通过列出可用的 MCP 工具（以
mcp__vercel__*为前缀的工具）检查 MCP 服务器。 - 如果有 MCP，仍优先使用 CLI 进行实际部署（CLI 文件上传更稳定），部署后如需查询项目/域名/环境变量，可使用 MCP。
- 如果用户坚持使用 MCP: 按照文档 https://vercel.com/docs/mcp 进行身份验证，然后使用相应的 MCP 工具。
第二步 — 检测框架 + 项目结构
读取项目根目录中的文件以确定框架：
| 文件 | 框架 |
|---|---|
next.config.js / next.config.mjs / next.config.ts | Next.js |
vite.config.js / vite.config.ts | Vite (React/Vue/Svelte) |
package.json 包含 "react-scripts" | Create React App |
package.json 包含 "astro" | Astro |
package.json 包含 "@remix-run/dev" | Remix |
仅有 index.html + 资源文件，无 package.json | 静态 HTML |
有 package.json 但不符合上述模式 | 询问用户框架类型，或让 Vercel 自动检测 |
记录以下信息:
- 从
package.json(scripts.build) 获取构建命令 - 输出目录（Next:
.next、Vite:dist、CRA:build、静态:.） - 所需的 Node 版本（来自
engines.node或.nvmrc）
→ 阅读相应的参考文档:
- React/Vite →
references/react-vite.md - Next.js →
references/nextjs.md - 静态 HTML →
references/static-html.md
第三步 — 生成 vercel.json（如需要）
Next.js: Vercel 完全自动检测，无需 vercel.json，除非需要自定义请求头或重定向。
Vite / CRA (SPA 路由): 需要 vercel.json 将所有路由重写为 index.html，以便客户端路由正常工作：
{
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}
静态 HTML: 通常不需要。如果网站有多个页面（thank-you.html、privacy.html），则无需重写。如果只包含 index.html + JS 路由器，则需要像 SPA 一样重写。
安全头（推荐用于生产环境）:
{
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
]
}
规则: 仅在用户确实需要时创建 vercel.json。创建不必要的文件 = 仓库噪音。
第四步 — 部署前检查清单
在运行 vercel 之前，验证以下内容：
- 存在
.gitignore文件，并包含.vercel/、node_modules/、.env*（绝不提交 secrets） - 代码中的文件路径均为 小写 + 相对路径（Linux 区分大小写）
- 无硬编码的
localhostURL - 外部脚本/样式表均使用
https:// - 如果 Next.js 使用了环境变量 → 已准备好需要设置的环境变量列表
- 如果存在
package.json→npm install（或其他等效命令）可在本地运行
如果发现明显问题（例如 HTML 中硬编码了 localhost），先修复 再部署。
第五步 — 部署
首次部署项目（尚无 .vercel/project.json）:
vercel --prod --yes
--yes 标志接受框架自动检测的所有默认设置。Vercel 将:
- 询问作用域（使用
--yes时会自动选择用户的账户） - 检测框架预设
- 设置构建命令和输出目录
- 推送代码、构建、部署
如果需要自定义项目名称 或用户希望链接到现有项目：
vercel link # 链接到现有项目（交互式）
vercel --prod # 链接后部署
部署预览（非生产环境）:
vercel
→ 返回预览 URL，格式如 https://<project>-<hash>.vercel.app，用于在生产环境推广前进行测试。
重新部署（项目已链接）:
vercel --prod
捕获输出 — 解析 stdout 以获取：
Production: https://<project>.vercel.appInspect: https://vercel.com/...
立即向用户报告这两个 URL。
第六步 — 验证 + 报告
部署成功后：
- HTTP 检查 live URL，使用
curl -I https://<project>.vercel.app— 验证状态码 200 且 SSL 已激活。 - 向用户报告，采用以下格式：
## ✅ 部署成功
**Live URL**: https://<project>.vercel.app
**Inspect / Logs**: https://vercel.com/<account>/<project>/<deployment-id>
**框架**: <Next.js | Vite | CRA | 静态 HTML>
**构建耗时**: <Xs>
### 下次部署
只需运行: `vercel --prod`
### 可选操作
- 设置自定义域名 → 告诉我 `setup domain <yourdomain.com>`
- 设置环境变量 → 告诉我 `add env <KEY>`
- 查看日志 → `vercel logs`
- 如果用户要求自定义域名 → 阅读
references/domains.md并提供 DNS 配置指导。
边缘情况与恢复
本地正常但 Vercel 构建失败
常见原因：
- 大小写敏感:
import './Components/Header'在本地 Mac 上可运行，但如果实际目录是components，在 Linux 上会失败。修复：按实际大小写重命名。 - 缺少依赖: 包位于
devDependencies但运行时需要 → 移至dependencies。 - Node 版本不匹配: 在
package.json或.nvmrc中添加"engines": { "node": "20.x" }。
→ 使用 vercel logs <deployment-url> 获取日志，阅读、修复、重新部署。
项目已链接到错误的账户/项目
rm -rf .vercel/ 然后重新运行 vercel --prod --yes。或者使用 vercel link 选择正确的项目。
生产环境变量
vercel env add <KEY> production
# 在提示时粘贴值
vercel env pull .env.production.local # 如果需要，拉取到本地
避免提交 .env* 文件。如果尚未添加，请将其添加到 .gitignore。
认证过期
CLI 令牌可能会过期。如果 vercel whoami 报告未授权 → 重新运行 vercel login。
按框架的详细参考
阅读与项目框架匹配的参考文档：
| 框架 | 参考文档 |
|---|---|
| Next.js（App / Pages Router） | references/nextjs.md |
| React（Vite / CRA） | references/react-vite.md |
| 静态 HTML | references/static-html.md |
| 自定义域名 + DNS | references/domains.md |
| 错误与故障排除 | references/troubleshooting.md |
原始参考
- Vercel CLI 文档: https://vercel.com/docs/cli
- Vercel 构建配置: https://vercel.com/docs/projects/project-configuration
- Vercel 限制（免费套餐）: https://vercel.com/docs/limits
- 状态页面: https://www.vercel-status.com