Next.js 部署到 Vercel 完整指南：环境变量、域名配置与性能监控

凌晨三点，我盯着浏览器里 Vercel 的 500 错误页面，心里一万头草泥马奔腾。

环境变量明明在 Vercel Dashboard 里配置了，为什么 API 还是返回 undefined？我把 .env.local 检查了三遍，重新部署了两次，甚至清空了浏览器缓存——还是不行。

直到半小时后，我才发现问题出在 NEXT_PUBLIC_ 这个前缀上。那一瞬间，我真想给当初没看文档的自己两巴掌。

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

不知道你有没有遇到过类似的情况：Next.js 项目本地跑得好好的，一部署到 Vercel 就各种诡异问题。环境变量不生效、自定义域名配置半天还是 404、SSL 证书报错导致无限重定向…

说实话，Vercel 的部署流程确实简单，但”简单”和”不踩坑”是两回事。那些藏在细节里的配置陷阱，往往会让你在凌晨三点抓狂。

这篇文章会带你走完 Next.js 部署 Vercel 的完整流程，从最基础的一键部署，到环境变量的正确配置，再到自定义域名绑定和性能监控。重点是，我会把那些文档没告诉你、但你一定会踩的坑全部标出来。

看完这篇，你至少能省下三个凌晨三点。

基础部署（5分钟上线）

一键部署的正确姿势

Vercel 的部署流程确实够简单：把代码推到 GitHub，连接 Vercel，点几下鼠标——搞定。但这个”简单”背后藏着不少细节。

先说最基础的流程。你的 Next.js 项目需要先推到 Git 仓库（GitHub、GitLab 或 Bitbucket 都行）。然后打开 vercel.com，用 GitHub 账号登录，点击 “Import Project”。

Vercel 会自动扫描你的仓库，检测到 Next.js 项目后，它会自动配置构建命令和输出目录。你基本不用动：

Build Command: next build
Output Directory: .next
Install Command: npm install

点击 Deploy，等个一两分钟，你就会拿到一个 your-project.vercel.app 的 URL。这时候，Vercel 已经帮你把静态资源（JS、CSS、图片）扔到了 Edge Network 上——全球 CDN 加速，开箱即用。

但这里有个新手容易忽略的细节：检查你的 package.json。

如果你的 build 脚本写的不是 next build，或者依赖项里缺了 next、react、react-dom，部署会直接失败。我见过有人把 build 脚本写成 webpack，然后怎么都部署不上去，最后发现 Vercel 压根没找到 Next.js。

还有就是 DPS 工作流——Develop, Preview, Ship。听起来挺唬人，其实就是：

• Develop：本地开发，npm run dev
• Preview：你创建 Pull Request 或者 push 到非主分支，Vercel 自动生成一个预览 URL，给你测试
• Ship：合并到 main 分支，Vercel 自动部署到生产环境

这个机制超级好用。比如你在开发新功能，提了个 PR，Vercel 会自动生成一个 your-project-git-feature-branch.vercel.app 的链接，你可以直接发给产品经理或者测试同学看效果，完全不影响线上环境。

部署后第一件事：检查构建日志

部署成功后，先别急着庆祝。点开 Vercel Dashboard，进入你的项目，找到 “Deployments” 标签页，点进最新的那次部署。

你会看到详细的构建日志。这个日志能告诉你：

1. 依赖安装用了多久：如果超过1分钟，可能是 node_modules 太大，或者网络慢
2. 构建过程有没有警告：比如 TypeScript 类型错误、ESLint 规则警告
3. 生成了多少静态页面：Next.js 会告诉你哪些页面是 SSG（Static Site Generation），哪些是 SSR（Server-Side Rendering）

我第一次部署时，构建日志里飘了一堆 TypeScript 报错，但部署居然成功了。后来才知道，Vercel 默认不会因为 TypeScript 错误阻止部署——除非你在 next.config.js 里开启 typescript.ignoreBuildErrors: false。

还有个容易被忽略的点：构建成功不代表页面能正常访问。

我见过有人部署成功，打开页面却是 500 错误，最后发现是 API 路由里用了 Node.js 的 fs 模块读取本地文件——Edge Functions 根本不支持文件系统操作。Vercel 的无服务器函数（Serverless Functions）是隔离的，每次请求都是独立的环境，你不能指望文件会持久化。

环境变量配置（最容易踩坑）

环境变量的三个层级

好，重头戏来了。环境变量这块确实挺绕的，我第一次配置时也在这里卡了半小时。

Vercel 把环境分成三种：Production（生产）、Preview（预览）、Development（开发）。简单说：

• Production：用户访问的正式环境，对应你的 main 分支
• Preview：你提 PR 或 push 到其他分支时，Vercel 自动生成的测试环境
• Development：你本地跑 npm run dev 的环境

这三种环境可以配不同的变量。比如数据库连接串，生产环境用真实数据库，预览环境用测试数据库，开发环境用本地数据库。

本地开发怎么配？

在项目根目录创建 .env.local 或 .env.development：

# .env.local
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here

.env.local 会被 Git 忽略（记得加到 .gitignore），这样你的 API key 不会泄露到代码仓库。

Vercel 部署怎么配？

打开 Vercel Dashboard → 进入你的项目 → Settings → Environment Variables。

这里你会看到三个复选框：Production、Preview、Development。勾选哪个，变量就在哪个环境生效。

比如我要配一个数据库连接串，只在生产环境用：

Name: DATABASE_URL
Value: postgresql://prod-server:5432/prod-db
Environment: ✅ Production

保存后，重新部署，变量就生效了。

容易踩的坑：配置后没重新部署。

Vercel 不会自动重新部署，你改了环境变量，得手动触发一次部署（或者 push 一次代码），变量才会更新到运行环境。

客户端 vs 服务端变量

这是最坑人的部分。我凌晨三点踩的就是这个坑。

Next.js 的环境变量分两种：

1. 服务端变量：只在服务端代码（API 路由、getServerSideProps、getStaticProps）里能访问
2. 客户端变量：需要加 NEXT_PUBLIC_ 前缀，会被内联到浏览器的 JS 代码里

举个例子：

# 服务端变量（安全）
DATABASE_URL=postgresql://...
API_SECRET_KEY=abc123

# 客户端变量（会暴露）
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Site

DATABASE_URL 和 API_SECRET_KEY 只能在服务端访问，浏览器里拿不到。但 NEXT_PUBLIC_API_BASE_URL 会被直接编译到 JS 文件里，任何人打开浏览器控制台都能看到。

我踩的坑是这样的：

我有个 API key，需要在客户端调用第三方接口。我一开始没加 NEXT_PUBLIC_ 前缀，结果浏览器里一直报 undefined。

后来我加了前缀，API key 确实能用了——但它被直接暴露在浏览器代码里了。任何人打开 DevTools，搜索 NEXT_PUBLIC_，我的 key 一览无余。

正确做法是什么？

不要在客户端直接调第三方 API。把请求放到 Next.js 的 API 路由里：

// app/api/data/route.ts (服务端)
export async function GET() {
  const res = await fetch('https://api.example.com', {
    headers: {
      'Authorization': `Bearer ${process.env.API_SECRET_KEY}` // 安全
    }
  })
  return res.json()
}

// app/page.tsx (客户端)
const data = await fetch('/api/data') // 调自己的 API，不暴露 key

这样，API key 只在服务端用，永远不会泄露到浏览器。

还有个细节：NEXT_PUBLIC_ 变量是在构建时内联的，不是运行时。意思是，你改了变量，必须重新 build，才能生效。

环境变量同步技巧

团队协作时，环境变量是个麻烦事。你不能把 .env.local 提交到 Git，但新同事 clone 代码后，又不知道要配哪些变量。

Vercel 提供了一个命令：

阿里云 - 开发者上云首选，轻量服务器专享 8.5 折优惠，助力项目快速上线

领取 8.5 折优惠 →推广

vercel env pull .env.local

这个命令会把 Vercel 上配置的环境变量（Development 类型的）拉到本地的 .env.local 文件。

前提是你得先装 Vercel CLI：

npm i -g vercel
vercel link  # 关联你的项目
vercel env pull

不过注意，这个命令只会拉 Development 环境的变量。Production 和 Preview 的变量不会拉下来（安全考虑）。

另一个技巧：用 .env.example 做模板。

在项目根目录创建 .env.example，列出所有需要的变量名（不写值）：

# .env.example
DATABASE_URL=
API_KEY=
NEXT_PUBLIC_API_BASE_URL=

把这个文件提交到 Git。新同事 clone 代码后，复制一份改成 .env.local，填入自己的值就行了。

Vercel 的环境变量总大小限制是 64KB，Edge Function 单个变量限制 5KB。一般项目不会超，但如果你要存 JWT 公钥、base64 编码的图片之类的，可能会踩到这个坑。

自定义域名配置

域名绑定三步走

your-project.vercel.app 这种域名看着太业余，而且 *.vercel.app 在国内已经被墙了。如果你想让国内用户正常访问，绑定自己的域名是必须的。

第一步：在 Vercel 添加域名

打开 Vercel Dashboard → 进入你的项目 → Settings → Domains。

点击 “Add”，输入你的域名（比如 example.com 或 blog.example.com），点击 Add。

Vercel 会检测你的域名，然后告诉你需要配置哪些 DNS 记录。

第二步：配置 DNS

这里有两种方式：A 记录和 CNAME 记录。

如果你要绑定根域名（example.com）：

Type: A
Name: @
Value: 76.76.21.21

如果你要绑定子域名（blog.example.com）：

Type: CNAME
Name: blog
Value: cname.vercel-dns.com

针对国内用户的特殊配置：

如果你的用户主要在国内，建议用 cname-china.vercel-dns.com 替代 cname.vercel-dns.com。这是 Vercel 专门为中国大陆优化的 CNAME 地址。

Type: CNAME
Name: blog
Value: cname-china.vercel-dns.com

或者用 A 记录指向国内友好的 IP：

Type: A
Name: @
Value: 76.223.126.88 或 76.76.21.98

配置好 DNS 后，等个几分钟到几十分钟（取决于你的 DNS 服务商），Vercel 会自动检测到配置生效。

第三步：验证

回到 Vercel Dashboard，刷新页面。如果域名旁边显示绿色的 “Valid Configuration”，就说明配置成功了。

打开浏览器，访问你的域名，应该能看到你的 Next.js 项目了。

容易踩的坑：DNS 配置不对。

我见过有人把 CNAME 的 Name 写成完整域名（blog.example.com），而不是 blog。结果 DNS 解析失败，域名一直生效不了。

还有人把 A 记录的 IP 写错了，或者 DNS 服务商缓存没刷新，导致等了半小时还是 404。

SSL 证书自动配置

好消息是，Vercel 会自动帮你申请 SSL 证书（Let’s Encrypt）。你不用做任何额外配置，HTTPS 就能用了。

域名配置生效后，Vercel 会自动申请证书，大概需要几分钟。你会在 Domains 页面看到 “Certificate Status: Provisioning”，等一会儿就会变成 “Active”。

证书申请成功后，访问 https://example.com，就能看到小绿锁了。

但有个坑：证书不匹配导致无限重定向。

如果你的域名同时配置了根域名（example.com）和 www 子域名（www.example.com），Vercel 会默认把其中一个重定向到另一个。

但如果你的 DNS 配置有问题，或者 SSL 证书只申请了其中一个域名，就会出现无限重定向——浏览器一直在 http://example.com 和 https://www.example.com 之间来回跳。

解决办法：确保你在 Vercel 同时添加了 example.com 和 www.example.com 两个域名，DNS 也都配置正确。

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

还有就是，某些 DNS 服务商的 SSL/TLS 设置需要开启 “完全加密” 模式。如果设置成 “灵活加密”，可能会导致证书不匹配。

如何检查 SSL 配置是否生效？

打开浏览器，访问 https://example.com，点击地址栏的小锁图标，查看证书详情。如果看到 “Issued by: Let’s Encrypt”，就说明证书配置成功了。

或者用命令行检查：

curl -I https://example.com

看看返回的 HTTP 状态码是不是 200，有没有 Strict-Transport-Security 头（HSTS）。

子域名和多域名策略

www 和根域名的双向配置

很多人会同时配置 example.com 和 www.example.com，然后把其中一个重定向到另一个。

Vercel 的做法是：你在 Domains 页面添加两个域名，Vercel 会自动处理重定向。你可以在 Settings 里选择 “Primary Domain”，另一个会自动重定向到主域名。

多语言站点的域名策略

如果你的 Next.js 项目支持多语言（i18n），可以为不同语言绑定不同的子域名：

• en.example.com → 英文版
• zh.example.com → 中文版
• ja.example.com → 日文版

在 Vercel 的 Settings → Domains 里分别添加这些子域名，然后在 next.config.js 里配置 i18n：

module.exports = {
  i18n: {
    locales: ['en', 'zh', 'ja'],
    defaultLocale: 'en',
    domains: [
      { domain: 'en.example.com', defaultLocale: 'en' },
      { domain: 'zh.example.com', defaultLocale: 'zh' },
      { domain: 'ja.example.com', defaultLocale: 'ja' },
    ],
  },
}

Preview 分支绑定独立域名

如果你想给预览环境（比如 staging 分支）绑定一个独立域名，可以在 Domains 页面添加 staging.example.com，然后选择 “Git Branch” 为 staging。

这样，每次你 push 代码到 staging 分支，Vercel 就会自动部署到 staging.example.com，而不影响生产环境。

性能监控与优化

Vercel Analytics 和 Speed Insights

部署上线后，你肯定想知道：页面加载快不快？用户体验怎么样？有没有性能瓶颈？

Vercel 提供了两个免费的分析工具：Analytics（用户行为分析）和 Speed Insights（性能分析）。

快速接入 Speed Insights

如果你用的是 Next.js App Router（Next.js 13+），接入超级简单：

npm install @vercel/speed-insights

然后在根布局里加一行：

// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
      </body>
    </html>
  )
}

部署后，Vercel Dashboard 的 “Speed Insights” 标签页就会开始收集数据。

核心 Web Vitals 监控

Speed Insights 会自动追踪 Google 定义的三个核心性能指标：

1. FCP (First Contentful Paint)：页面首次渲染内容的时间。理想值 < 1.8s
2. LCP (Largest Contentful Paint)：最大内容绘制时间。理想值 < 2.5s
3. CLS (Cumulative Layout Shift)：页面布局稳定性。理想值 < 0.1

这些数据来自真实用户的浏览器（Real User Monitoring），不是实验室数据。你能看到不同地区、不同设备、不同浏览器的性能表现。

如何根据 Speed Insights 做性能调整？

举个例子。我之前有个项目，Speed Insights 显示 LCP 一直在 4s 左右，远超理想值 2.5s。

我点开详情，发现问题出在首页的 Hero 图片上——一张 2MB 的 PNG 图片，没压缩，没用 Next.js 的 <Image> 组件。

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

我把图片换成 WebP 格式，用 next/image 组件自动处理，LCP 直接降到了 1.8s。Speed Insights 的分数从 60 分涨到了 95 分。

这就是真实用户数据的价值。实验室跑分再高，也不如真实用户的体验数据来得准。

Analytics 看用户行为

Vercel Analytics 能告诉你：

• 哪些页面访问量最高
• 用户从哪里来（流量来源）
• 不同地区的访问量分布
• 哪些页面的跳出率高

这个功能对个人项目是免费的（每月 10 万次浏览），对商业项目需要付费。

进阶配置

自定义构建命令

如果你的项目构建流程比较特殊，可以在 Vercel Dashboard → Settings → Build & Development Settings 里自定义构建命令。

比如你用 pnpm 而不是 npm：

Build Command: pnpm build
Install Command: pnpm install

或者你需要在构建前运行脚本：

Build Command: npm run prebuild && npm run build

Edge Functions 和 Edge Middleware

Vercel 支持在全球边缘节点运行代码（Edge Functions），响应速度比传统 Serverless Functions 快很多。

如果你的 Next.js 项目用了 Middleware，Vercel 会自动把它部署为 Edge Middleware。比如做鉴权、重定向、A/B 测试，都可以在边缘节点完成，不用回源。

// middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request) {
  if (!request.cookies.get('token')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

Serverless Functions 超时配置

Vercel 的 Serverless Functions 默认超时时间是 10 秒（免费套餐）。如果你的 API 路由需要处理耗时操作（比如调用第三方 API、生成 PDF），可能会超时。

付费套餐可以延长到 60 秒。或者你可以把耗时操作放到后台队列（比如用 Inngest、Trigger.dev），不阻塞 HTTP 请求。

部署保护：密码保护预览环境

如果你的预览环境（Preview）不想被公开访问，可以在 Settings → Deployment Protection 里开启密码保护。

勾选 “Password Protection for Previews”，设置一个密码。之后访问预览 URL 时，会要求输入密码才能查看。

这个功能对保护敏感数据或未完成的功能特别有用。

总结

说了这么多，你现在应该对 Next.js 部署到 Vercel 的完整流程有清晰的认识了。

从最基础的一键部署，到环境变量的三种层级配置，再到自定义域名绑定和 SSL 证书，最后到性能监控和进阶配置——这些都是你在实际项目中一定会遇到的问题。

环境变量那块确实绕，但记住核心原则：服务端变量不加前缀，客户端变量加 NEXT_PUBLIC_ 前缀，API key 永远不要暴露到客户端。这个坑，我替你踩过了。

域名配置看起来简单，但 DNS 的细节容易出错。特别是国内用户，记得用 cname-china.vercel-dns.com 或者 76.76.21.21 这些针对国内友化的地址，不然你的站点可能会被墙。

性能监控这块，Speed Insights 真的很好用。真实用户数据比实验室跑分准太多了。看到 LCP 超过 2.5 秒，就去检查图片、字体、首屏渲染——往往一个调整就能让分数涨 30 分。

现在你已经掌握了 Next.js 部署到 Vercel 的完整流程。打开终端，把你的第一个项目推到 GitHub，连接 Vercel，看着自动部署完成的那一刻——相信我，那种成就感会让你觉得这十分钟的阅读完全值得。

遇到问题欢迎留言讨论，我会尽量回复。祝部署顺利！

17 分钟阅读 · 发布于: 2025年12月20日 · 修改于: 2026年1月22日

Easton

技术开发