Vercel 部署与自定义域名避坑指南：从 push 到 https 全流程

把项目推到 GitHub，Vercel 自动构建上线——这第一步确实「只要点几下」。但从「部署成功」到「域名稳定可访问、HTTPS 正常、环境变量到位」，中间藏着一堆会卡住人的坑。本文按现象 → 诊断 → 解法 → 验证组织，是独立开发者把 Next.js 项目搬上 Vercel 的排障手册。

一、部署链路：先对齐「谁触发、什么时候生效」

典型链路：git push origin main → GitHub Webhook → Vercel 拉代码 → 安装依赖 → 构建 → 部署到边缘网络 → 更新域名指向。

关键认知：

• 部署是异步的，push 之后要等 1-3 分钟（构建快的项目 40 秒左右）。刚 push 完立刻刷新页面看到旧版本是正常的，别急着怀疑。
• Vercel 有预览部署（每个 PR/分支一个 URL）和生产部署（main 分支）。改错了分支会「部署成功但线上没变化」。
• 部署状态看 Vercel 控制台的 Deployments 页：Building → Ready → Error。Error 时点进去看 Build Logs，第一行报错通常就是根因。

二、自定义域名：最常卡住的环节

现象 1：域名在 Vercel 加了，但浏览器打不开（DNS 未生效）

诊断顺序：

1. nslookup yourdomain.com —— NXDOMAIN 说明域名商那边根本没解析，先别怪 Vercel
2. dig yourdomain.com @8.8.8.8 —— 用公共 DNS 验证，绕过本地缓存
3. Vercel 控制台 Project → Settings → Domains，看状态是 Valid Configuration 还是 Invalid

解法：Vercel 添加域名后会给出两条 A 记录（76.76.21.21）+ 一条 CNAME（cname.vercel-dns.com）。去域名商（阿里云/腾讯云/Cloudflare）把记录加上。根域用 A 记录，www 子域用 CNAME。加完等 DNS 传播（几分钟到几小时），Vercel 域名状态变绿就通了。

⚠️ 踩坑实录：域名拼错是最隐蔽的问题——pan.bitol.tech 和 pan.bitou.tech 差一个字母，nslookup 直接 NXDOMAIN，排查半小时才发现是域名本身不存在。先在浏览器直接访问确认域名没拼错。

现象 2：www 和根域只有一个能开

解法：在 Vercel Domains 里把两个都加上，Vercel 会自动配置 301 跳转（默认 www → 根域，或按你设置的 Redirect 规则）。手动配的话：根域 301 到 www 或反之，二选一，别都指向又互相跳（会形成重定向循环）。

现象 3：HTTPS 证书「永远在申请中」

解法：Vercel 自动签发 Let's Encrypt 证书，一般几分钟内完成。卡住的原因通常是：① DNS 还没生效（证书验证失败）；② 域名记录类型配错（A 写成了 CNAME）；③ 域名有 CAA 记录限制（CAA 里 issue 要包含 letsencrypt.org，Vercel 用的是 Let's Encrypt）。修完 DNS 后可以手动触发：Domains 页删除重新添加，或等自动重试。

现象 4：datafun.vercel.app 能开，自定义域名 404

解法：大概率是重定向/rewrite 规则或 basePath 配置问题。检查 next.config.js 的 basePath（如果设置了 /blog 之类前缀，根域访问会 404）。另外确认添加域名时选的是对的 Project——多项目共用域名时会串。

三、构建失败：依赖与环境变量

现象 5：本地能 build，Vercel 上失败

排查：本地和云端差异三件套：

1. Node 版本：package.json 加 "engines": { "node": ">=20" } 或在 Vercel 项目 Settings → General → Node.js Version 指定。云端默认版本和本地 nvm 版本不一致是最常见根因。
2. 环境变量：.env.local 不会上传（在 .gitignore 里）。去 Settings → Environment Variables 补齐，注意 Production / Preview / Development 三个环境分别生效，只加了 Development 的变量，生产构建时就是 undefined。
3. 依赖锁定：package-lock.json / pnpm-lock.yaml 是否提交？没提交的话云端每次安装依赖版本漂移，偶现失败。

现象 6：构建日志报内存溢出（heap out of memory）

解法：Next.js 大项目常见。在 package.json build 脚本加："build": "NODE_OPTIONS=--max-old-space-size=4096 next build"。还不行就检查是不是在构建时连了数据库做 SSG——dynamic = "force-dynamic" 或 unstable_noStore() 把动态页面挪到请求时渲染，别在构建期查库。

四、线上行为：重定向、缓存与 Analytics

现象 7：HTTP 访问不会自动跳 HTTPS

解法：Vercel 默认强制 HTTPS，如果没跳，检查 Settings → Domains 里域名状态是否是 Valid，以及是否有自定义 redirect 规则干扰。手动兜底：next.config.js 里 redirects() 加一条 http → https 永久跳转。

现象 8：部署了新版，但浏览器还是旧页面

解法：CDN 缓存 + Service Worker 双缓存。Vercel 的静态资源带 hash 版本号，一般自动失效；顽固场景：① 浏览器强缓存（Cmd+Shift+R 硬刷新）；② 你项目里注册了 Service Worker（PWA）——SW 默认不更新，需要版本管理；③ 域名本身被本地 DNS 缓存（dscacheutil -flushcache macOS）。

现象 9：Vercel Analytics 里 Referrers 恒为空

这不是数据缺失，是结论：微信/飞书等聊天 App 内打开链接会剥离 HTTP Referer，所以社交分享流量在 Referrers 维度永远为空（但计入 Visitors）。想追踪渠道：给分享链接加 UTM 参数（?utm_source=微信&utm_medium=群聊），在 Analytics 的 UTM Parameters 标签查看——这是社交分享型产品唯一的渠道追踪正解。

五、快速验证清单

nslookup yourdomain.com          # 1. DNS 解析是否生效
dig yourdomain.com @8.8.8.8      # 2. 用公共 DNS 绕过缓存
curl -I https://yourdomain.com   # 3. HTTPS 是否 200 + 证书正常
curl -I http://yourdomain.com    # 4. HTTP 是否 301 到 HTTPS
curl -I https://www.yourdomain.com  # 5. www 是否 301 到根域

全绿 = 部署链路稳定。后续每次迭代只需要：改代码 → push → 等 Ready → 刷新验证。

延伸阅读：本站的 Webpack 构建排障索引 和 Nginx 网关排障索引 覆盖构建与网关侧的更多问题。