Vercel 部署全流程与排障手册

2026-06-11Vercel部署CI/CDDevOps排障

为什么选 Vercel

Vercel 是前端项目的最佳部署平台之一。核心优势：零配置部署、自动 Git 集成、全球 CDN、自动 SSL 证书、Serverless Functions 支持。免费额度对个人项目和中小型站点完全够用。

部署方式对比

方式命令自动化程度适用场景
CLI 手动部署vercel --prod --yes手动触发快速上线、临时测试
Git 自动部署git push + Vercel 监听全自动日常工作流、团队协作
API 部署POST /v13/deployments可编程CI/CD 集成、自定义流水线

CLI 部署完整流程

# 1. 安装 Vercel CLI
npm i -g vercel

# 2. 登录（一次性）
vercel login

# 3. 在项目目录中初始化（一次性）
vercel link     # 关联到 Vercel 项目

# 4. 每次更新后部署
npm run build              # 先本地构建验证
vercel --prod --yes        # 部署到生产环境

域名绑定

方式一：CLI

vercel domains add your-domain.com

方式二：API（可编程）

# 先获取 Vercel token
# Windows: 存储在系统凭据管理器，服务名 com.vercel.vercel-cli
# 通过 @napi-rs/keyring 或 vercel whoami --token 获取

# 绑定域名
curl -X POST "https://api.vercel.com/v10/projects/{project}/domains" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "your-domain.com"}'

SSL 注意事项：Vercel 自动签发 Let's Encrypt 证书。新注册的域名（< 90 天）可能受 Let's Encrypt 速率限制。如果域名已注册超过 90 天，证书签发非常顺畅。

常见问题排查

错误现象原因解决方案
构建失败：Cannot read properties of undefined Astro 5.x import.meta.glob API 变更 改为 { eager: true }
部署命令找不到项目 PowerShell Start-Job 改变了工作目录 始终 cd 到项目根目录再执行
vercel.json 构建警告 name 和 public 字段在新版中弃用 从 vercel.json 中移除这两个字段
域名验证失败（DNS） DNS 未正确配置 CNAME/A 记录 检查 DNS 配置，等 propagation（最多 48h）
SSL 证书签发失败 域名 < 90 天或 DNS 未传播 等待域名注册满 90 天，确认 DNS 已生效

vercel.json 最佳配置

{
    "buildCommand": "npm run build",
    "outputDirectory": "dist",
    "installCommand": "npm install",
    "framework": "astro",
    "rewrites": [
        { "source": "/(.*)", "destination": "/index.html" }
    ]
}

注意：不要写 "name" 和 "public" 字段——这些在新版 Vercel CLI 中已弃用，会导致构建警告。保持 vercel.json 最小化，只写必要的配置。

自动化部署工作流（推荐）

# 日常更新流程
1. 修改内容（笔记、代码等）
2. node generate-search-index.js      # 更新搜索索引
3. npm run build                        # 本地构建验证
4. git add -A && git commit -m "..."
5. git push                             # Vercel 自动触发部署
未标记