vercel-deployment

Vercel 部署

概述

Vercel 是一个云平台，可用于部署前端框架和无服务器函数，并提供自动 CI/CD、预览部署和边缘基础设施。项目可通过 vercel.json（或程序化配置 vercel.ts）、Vercel 仪表板或 Vercel CLI 进行配置。

适用场景： 静态网站、SSR 框架（Next.js、SvelteKit、Nuxt）、无服务器 API 路由、边缘函数、每个拉取请求对应的预览环境、单体仓库部署。

不适用场景： 长时间运行的后端进程（使用容器）、WebSocket 服务（使用专用基础设施）、高负载计算任务（使用云虚拟机）、需要持久文件系统访问的应用程序。

快速参考

模式	工具 / API	关键点
项目配置	vercel.json 或 vercel.ts	位于项目根目录，控制构建、路由和函数
重写	rewrites 数组	将请求路由到目标地址，URL 保持不变
重定向	redirects 数组	更改 URL，permanent: true 表示 301
标头	headers 数组	按路径模式设置自定义响应标头
简洁 URL	cleanUrls: true	去掉 .html 扩展名
尾部斜杠	trailingSlash: false	保持 URL 格式一致
环境变量	仪表板或 vercel env	按生产、预览和开发环境设置作用域
自定义域名	项目设置 > 域名	根域名使用 A 记录，子域名使用 CNAME
预览部署	每个 PR 自动创建	每次推送都会获得唯一 URL
边缘函数	export const runtime = 'edge'	V8 隔离环境、低延迟、Node.js API 有限
无服务器函数	api/ 目录或框架路由	Node.js 运行时，可完整访问 API
通过 CLI 部署	vercel 或 vercel --prod	默认进行预览部署，使用 --prod 部署到生产环境
提升部署	vercel promote <url>	将现有预览部署提升到生产环境
单体仓库	为每个项目设置根目录	一个仓库，多个 Vercel 项目
GitHub 集成	推送时自动触发	无需配置 CI/CD，每个分支都有预览
程序化配置	使用 @vercel/config 的 vercel.ts	类型安全的动态配置替代方案
流式计算	新项目默认启用	处理多个请求的工作进程，默认持续时间为 300s
渐进式发布	增量发布并进行监控	逐步切换流量，并在触发条件满足时自动回滚
防火墙规则	vercel.json WAF 配置	通过仪表板、API 或配置文件拦截威胁

常见错误

错误	正确做法
使用 .env.production 存储预览专用值	使用范围限定为预览环境的 Vercel 环境变量
以为 VERCEL_URL 包含协议	手动添加 https:// 前缀；使用 VERCEL_PROJECT_PRODUCTION_URL 获取稳定的生产环境 URL
只添加根域名，不添加 www	同时添加 yourdomain.com 和 www.yourdomain.com，避免其中一个域名出现 404
在边缘函数中使用 Node.js API	边缘运行时仅使用 V8；fs、path、process 均不可用
静态重定向数量超过 1024	大量重定向规则（CSV/JSON/JSONL）请使用 bulkRedirects 属性
在边缘函数中创建 QueryClient 或进行数据获取，却未使用流式传输	边缘函数中的长时间操作请使用流式响应
将 maxDuration 设置为超过计划上限	Fluid compute 的默认值：300s；Hobby：60s，Pro：300s，Enterprise：最高 900s
自定义域名的 DNS 记录冲突	删除重复的 A 记录；仅保留指向 Vercel 的记录
在 CI 中部署前未等待构建完成	使用 vercel build，然后使用 vercel deploy --prebuilt，确保 CI 部署可靠
忽略 monorepo 根目录设置	在 Vercel 控制面板中为每个项目设置根目录，确保正确构建

委派

• 基础设施审查：使用 Task Agent 审核部署配置
• 环境调试：使用 Explore Agent 追踪环境变量问题
• CI/CD 流水线审查：使用 code-reviewer Agent 审查 GitHub Actions 工作流

参考资料

• 配置：vercel.json、构建、重写、重定向、标头
• 环境变量和自定义域名
• 边缘函数和无服务器函数
• CLI 命令和 CI/CD 集成