之前在技术选型时我一直关注前后端一体化的开发模式。做过几个中小型项目后有个感受非常明显框架能力再强部署和上线体验跟不上落地效率就会大打折扣。Next.js 作为 React 生态里成长最快的全栈框架搭配 Vercel 这个为它量身打造的部署平台几乎成了当下构建 Web 应用最顺手的组合之一。这篇教程会从零开始带你走一遍完整的实战流程先理解 Next.js 和 Vercel 各自解决什么问题然后本地环境搭建、创建项目、编写页面、配置环境变量最后把项目部署到 Vercel 并绑定自定义域名。全程给出可复制的命令、代码和配置并对高频报错做一次集中排查梳理。无论你是刚接触 React 的新手还是准备把项目交给前端团队维护的开发者这套内容都能直接上手。1. Next.js 与 Vercel 的核心概念1.1 Next.js 是什么Next.js 是一个基于 React 的元框架Meta Framework。我们平时用 Create React App 或 Vite 搭建的 React 项目本质上是一个纯前端单页应用SPA页面内容由浏览器里的 JavaScript 动态渲染搜索引擎爬虫能抓到的 HTML 往往只是一个空壳。Next.js 的核心理念是在 React 之上补充了完整的 Web 应用能力包括服务端渲染SSR每次请求在服务端生成完整 HTML返回给浏览器首屏更快SEO 更友好。静态站点生成SSG构建时生成静态 HTML部署到 CDN 后响应速度极快。增量静态再生ISR在静态页面基础上按一定时间间隔重新生成部分页面兼顾性能和内容更新。API Routes / Route Handlers在同一项目中直接编写后端接口省去单独维护 Node 服务的成本。文件系统路由把文件路径映射为页面路由无需手动配置路由表。1.2 Vercel 是什么Vercel 是一个前端云平台Frontend Cloud由 Next.js 团队打造。它提供的核心价值是让前端项目的部署变得极其简单关联 Git 仓库后每次git push都会自动触发构建和预览部署。为每个分支生成独立的预览 URL方便团队协作和代码评审。自动分配 CDN、HTTPS 证书、边缘网络加速。提供 Serverless Functions 运行环境让 Next.js 的后端接口和无服务器函数可以无缝运行。支持环境变量、自定义域名、监控、日志等一系列生产环境必备能力。把 Next.js 部署到 Vercel 可以理解为“官方原配”框架的很多高级特性比如中间件Middleware、边缘函数Edge Runtime、ISR 按区失效On-Demand Revalidation在 Vercel 上都有最完整的支持。1.3 为什么需要两者配合如果只用 Next.js 而自己购买服务器部署你需要自己处理 Node 服务进程管理、Nginx 反向代理、HTTPS 证书、日志收集、多环境配置等问题。这些工作不是不能做但要花不少精力。如果只用 Vercel 而不用 Next.js虽然 Vercel 也支持 Vite、Nuxt、Astro 等框架但很多平台特色功能无法完整发挥。两者的配合逻辑很清晰Next.js 负责应用的架构和开发体验Vercel 负责部署、托管和运维。对于团队合作或个人项目来说这套方案的学习成本低能快速把精力集中在业务代码上。2. 环境准备与版本说明在开始之前我们先确认本地开发环境。Next.js 基于 Node.js 运行你需要先安装好 Node.js 和包管理器。工具说明Node.js建议安装 18.17.0 及以上版本具体见下方说明npm / yarn / pnpm任意一个包管理器即可本文以 npm 为例Git用于版本管理和后续 Git 集成部署Vercel CLI可选用于命令行部署和本地环境变量管理版本需要根据你的项目实际情况调整。当前 Next.js 主流的稳定版本已经进入 App Router 时代本文示例以 App Router 为主同时会补充说明 Pages Router 和 App Router 的区别。如果你的 Node.js 版本较低建议先通过nvm这类工具升级 Node.js避免安装依赖时出现 engine 不兼容的报错。安装完成后在终端确认版本node -v npm -v git --version只要能正常输出版本号说明环境基本就绪。接下来我们创建一个示例项目项目名称定为nextjs-vercel-demo。3. 创建 Next.js 项目3.1 使用 create-next-app 初始化最简单的初始化方式是用官方脚手架npx create-next-applatest nextjs-vercel-demo执行过程中终端会询问几个配置选项常见的回答如下Need to install the following packages: create-next-applatest Ok to proceed? (y) y ✔ Would you like to use TypeScript? ... Yes ✔ Would you like to use ESLint? ... Yes ✔ Would you like to use Tailwind CSS? ... No ✔ Would you like to use src/ directory? ... Yes ✔ Would you like to use App Router? ... Yes ✔ Would you like to customize the default import alias (/*)? ... No这里有几个选项可以按项目需求自由选择TypeScript推荐开启。Next.js 对 TypeScript 的支持非常成熟类型检查能减少很多运行时错误。ESLint推荐开启Next.js 内置了自己的 ESLint 配置。Tailwind CSS如果项目需要快速写样式可以开启不开启也能正常使用 CSS Modules 或普通 CSS。src/ 目录推荐开启把代码放在src下结构更清晰。App Router推荐开启这是 Next.js 现在主推的路由模式。初始化完成后进入项目目录并启动开发服务器cd nextjs-vercel-demo npm run dev终端输出类似以下内容说明项目启动成功▲ Next.js 15.x.x - Local: http://localhost:3000 - Environments: .env.local浏览器访问http://localhost:3000就能看到 Next.js 默认的欢迎页。3.2 项目结构说明用脚手架创建的项目核心目录结构如下nextjs-vercel-demo/ ├── public/ │ ├── next.svg │ └── vercel.svg ├── src/ │ └── app/ │ ├── favicon.ico │ ├── globals.css │ ├── layout.tsx │ └── page.tsx ├── .gitignore ├── next.config.ts ├── package.json └── tsconfig.json这里有几个重要文件需要理解src/app/layout.tsx根布局文件所有页面都会包裹在这个布局里适合放全局导航、页脚、字体设置。src/app/page.tsx首页组件对应路由/。src/app/globals.css全局样式文件。next.config.tsNext.js 配置文件可以配置图片域名白名单、重定向、Header 等。.gitignore默认忽略node_modules、.next构建产物等。3.3 App Router 与 Pages Router如果你是第一次接触 Next.js可能会看到网上资料里写pages/api、_app.tsx这类写法那是旧版 Pages Router。从 Next.js 13 开始官方主推 App Router使用app目录并引入了 React Server Components 的概念。两张路由模式的核心区别是对比项Pages RouterApp Router入口目录pages/app/布局方式需要手动创建_app.tsx和自定义 Layout文件级layout.tsx天然支持嵌套布局数据获取getServerSideProps/getStaticPropsServer Component 中直接async函数加载状态需要额外处理loading.tsx、error.tsx约定文件推荐度旧项目仍维护新项目首选本文后面的示例全部基于 App Router。4. 编写一个完整的前后端联动页面4.1 创建环境变量文件接下来我们做一个带数据请求的完整示例用来演示 Next.js 的 SSR 能力、Route Handlers 和 Vercel 部署时的环境变量配置。在项目根目录创建.env.localtouch .env.local写入以下内容# 本地环境变量 NEXT_PUBLIC_API_BASE_URLhttp://localhost:3000 DEMO_MESSAGEHello from Vercel注意NEXT_PUBLIC_开头的变量会暴露给浏览器端代码适合放公开配置不带前缀的变量只存在于服务端适合放密钥等敏感信息。4.2 编写 Route HandlerApp Router 中接口函数放在路由目录下的route.ts文件里。我们创建一个服务端接口用于返回一条动态消息。文件路径src/app/api/message/route.tsimport { NextResponse } from next/server; export async function GET() { return NextResponse.json({ message: process.env.DEMO_MESSAGE || Hello from API, timestamp: new Date().toISOString(), }); }这个接口会在服务端运行读取环境变量DEMO_MESSAGE然后以 JSON 格式返回。本地可以通过http://localhost:3000/api/message访问。4.3 改写首页接下来修改首页让它通过服务端组件直接请求这个接口并把结果显示在页面上。文件路径src/app/page.tsxasync function getMessage() { const baseUrl process.env.NEXT_PUBLIC_API_BASE_URL || http://localhost:3000; const res await fetch(${baseUrl}/api/message, { cache: no-store }); if (!res.ok) { throw new Error(Failed to fetch message); } return res.json(); } export default async function Home() { const data await getMessage(); return ( main style{{ fontFamily: system-ui, sans-serif, padding: 2rem }} h1Next.js Vercel 部署示例/h1 p接口返回消息/p ul limessage: {data.message}/li litimestamp: {data.timestamp}/li /ul /main ); }这里有几个关键点Home组件是 async 函数说明它是一个 Server Component可以直接使用await获取数据。fetch的cache: no-store表示每次都从服务端重新请求不做静态缓存。在服务端组件中请求自己的 API 路由实际上会走一次 HTTP 请求。更高效的做法是直接操作数据库或调用内部函数但为了演示前后端链路这里保留这种写法。4.4 运行验证保存文件后浏览器访问http://localhost:3000页面应该能显示接口返回的消息和时间戳。这个请求是服务端发起的打开浏览器的“开发者工具 - Network”面板你会发现页面 HTML 里已经包含了最终渲染的内容这正是 SSR 的特征。5. 将项目部署到 Vercel项目本地运行正常后接下来进入核心环节部署到 Vercel。5.1 方式一通过 Git 仓库自动部署这是最推荐的方式。Vercel 与 Git 仓库的集成让每次代码提交都能自动构建发布。流程如下在 GitHub或 GitLab、Bitbucket上创建一个新仓库。在本地初始化 Git 并推送代码git init git add . git commit -m feat: init nextjs project git branch -M main git remote add origin https://github.com/你的用户名/nextjs-vercel-demo.git git push -u origin main打开 Vercel 官网使用 GitHub 账号登录。点击Add New - Project选择刚创建的仓库。如果检测到这是 Next.js 项目Framework Preset 会自动选择Next.js构建命令会自动填充为npm run build输出目录为.next。在Environment Variables区域添加之前本地使用过的变量DEMO_MESSAGE Hello from Vercel production NEXT_PUBLIC_API_BASE_URL https://你的项目域名.vercel.app这里要注意NEXT_PUBLIC_API_BASE_URL如果留空或还在用http://localhost:3000生产环境的服务端请求就会打到本地地址上导致接口返回 500。点击Deploy等待一两分钟Vercel 会自动完成安装依赖、构建、发布流程。页面会显示一个形如https://nextjs-vercel-demo.vercel.app的正式地址。5.2 方式二使用 Vercel CLI 部署如果你不想关联 Git 仓库或者只想快速验证效果可以使用命令行工具。先安装 CLInpm i -g vercel在项目根目录执行vercel第一次执行会在终端中要求登录、关联项目按提示操作即可。CLI 会读取本地环境变量并上传到 Vercel最终输出一个预览 URL。如果要部署到生产环境vercel --prod5.3 配置自定义域名部署成功后Vercel 会自动分配一个 HTTPS 证书默认域名已经可以使用。如果想绑定自己的域名进入项目 Dashboard找到Settings - Domains输入你的域名并添加。Vercel 会给出两条 DNS 解析记录按照提示到域名服务商处配置 CNAME 或 A 记录即可。域名解析生效后Vercel 会自动签发和续期 HTTPS 证书整个过程不需要在服务器上手工操作。5.4 环境变量的管理Vercel 上的环境变量按环境分为三类环境说明Production生产环境正式部署时使用Preview预览部署每个 Pull Request 都会生成独立 URLDevelopment本地vercel dev时使用进入 Dashboard 的Settings - Environment Variables可以分别添加不同环境下的变量。需要注意的是在环境变量值中插入的换行符需要写成\n否则可能解析异常。6. 核心特性SSR、SSG、ISR 与边缘函数部署到 Vercel 后Next.js 的很多特性会直接影响线上表现建议先理解这几个概念。6.1 服务端渲染与静态生成的取舍前面已经提到 SSG 和 SSR 的区别。在实际项目中判断标准很简单页面内容是否依赖用户身份如果依赖使用 SSR 或客户端渲染。页面内容对所有用户是否相同如果相同优先使用 SSG。页面是否需要频繁更新如果不需要实时更新可以用 ISR。在 App Router 中默认情况下组件是静态渲染的。如果组件使用了cookies()、headers()等动态 API或者使用了no-storeNext.js 会自动将其标记为动态渲染。6.2 使用 ISR 实现增量静态再生ISR 是一种折中方案。以博客文章为例页面可以构建时生成静态 HTML但每隔 60 秒重新验证一次如果源数据更新后台会悄悄重新生成页面。文件路径src/app/posts/[slug]/page.tsxinterface Post { slug: string; title: string; content: string; } // 模拟获取文章数据 async function getPost(slug: string): PromisePost { return { slug, title: Post: ${slug}, content: This is the content of ${slug}, }; } export default async function PostPage({ params }: { params: { slug: string } }) { const post await getPost(params.slug); return ( article h1{post.title}/h1 p{post.content}/p /article ); } // 返回所有可能的 slug用于静态生成 export async function generateStaticParams() { return [{ slug: first-post }, { slug: second-post }]; } // 每 60 秒重新验证一次 export const revalidate 60;部署后页面会在首次访问时生成静态版本之后 60 秒内的访问直接命中缓存超过 60 秒后触发后台重新生成。6.3 边缘函数与中间件Vercel 支持边缘运行时让代码在 Vercel 的全球边缘节点执行用户请求会直接被最近的节点处理延迟更低。中间件Middleware常用于身份校验、路径重写、访问控制等场景。文件路径src/middleware.tsimport { NextResponse } from next/server; import type { NextRequest } from next/server; export function middleware(request: NextRequest) { const isLoggedIn request.cookies.get(token)?.value; if (!isLoggedIn request.nextUrl.pathname.startsWith(/dashboard)) { return NextResponse.redirect(new URL(/login, request.url)); } return NextResponse.next(); } export const config { matcher: [/dashboard/:path*], };这个中间件运行在边缘环境不用等到 Node.js 服务启动就可以完成登录校验逻辑对性能敏感的场景很有帮助。7. 常见问题与排查思路在实际开发和部署中最容易踩坑的有以下几种情况。问题现象常见原因解决思路本地npm run dev报EACCES权限错误Node.js 安装位置权限不足不要使用 sudo 运行改用 nvm 管理 Node.js部署到 Vercel 后接口返回 500API 请求地址仍为 localhost或环境变量未配置检查生产环境变量确保NEXT_PUBLIC_API_BASE_URL指向线上域名npm run build时 TypeScript 报错类型不匹配运行npx tsc --noEmit定位问题ESLint 构建失败代码不符合 lint 规则先本地执行npm run lint修复页面数据不更新使用了默认静态渲染或缓存区分数据场景按需使用revalidate或no-store图片域名报错next/image默认不允许任意域名在next.config.ts中配置remotePatterns7.1 部署后接口 500 的排查步骤这是新手最容易遇到的问题按以下顺序排查进入 Vercel Dashboard打开项目的Logs查看具体错误信息。检查NEXT_PUBLIC_API_BASE_URL是否指向线上域名而不是 localhost。检查接口路由文件路径是否正确Route Handler 是否导出了对应的方法。确认next build在本地能成功如果本地都失败部署必然失败。检查.env.local是否被误提交到了 Git 仓库暴露的密钥需要立即轮换。7.2 .env.local 与 Git 提交Next.js 脚手架默认会在.gitignore中忽略.env*.local文件这是刻意设计的。本地环境变量不应提交到 Git 仓库尤其是涉及密钥的变量。生产环境变量应该统一在 Vercel Dashboard 中配置。8. 最佳实践与工程建议8.1 项目结构规范App Router 项目建议按功能模块组织src/ ├── app/ │ ├── (marketing)/ │ │ ├── page.tsx │ │ └── layout.tsx │ └── api/ ├── components/ │ ├── ui/ │ └── shared/ ├── lib/ │ └── api.ts └── types/用路由分组Route Groups来区分业务模块用components目录放可复用 UI用lib目录放数据请求和工具函数这样代码规模增大后依然容易维护。8.2 数据获取原则在 Server Component 中请求数据时遵循以下原则优先在服务端获取数据减少客户端网络请求。避免在客户端组件中直接请求自己的 API 路由通常可以直接调用数据层函数。静态内容用 SSG个性化内容用 SSR内容更新频率中等时用 ISR。对于第三方 API建议在服务端封装隐藏密钥并做错误处理。8.3 性能优化Next.js 自动做了很多性能优化但仍然需要关注使用next/image而不是原生img自动支持懒加载、响应式尺寸和 WebP 格式。使用next/font加载字体避免阻塞渲染。减少客户端组件范围默认先用 Server Component。对大型组件使用dynamic按需加载import dynamic from next/dynamic; const HeavyComponent dynamic(() import(../components/HeavyComponent), { loading: () pLoading.../p, });8.4 生产环境的安全边界密钥类环境变量永远不要加NEXT_PUBLIC_前缀。不要在客户端组件中直接读取服务端环境变量。对外暴露的 API 需要做鉴权时使用中间件或 Route Handler 服务端校验。涉及删除、更新等写操作时必须校验用户身份和参数合法性。保持依赖更新及时跟进 Next.js 的安全公告。8.5 使用预览部署提升团队协作效率Vercel 的 Preview Deployment 非常适合团队协作。每个 Pull Request 会生成一个独立 URL前端可以在这个地址验收效果后端可以提前联调接口产品经理也能直接看到最新改动。这个体验是传统“买服务器 手动部署”很难实现的。9. 总结与学习路线到这里我们完整走了一遍 Next.js Vercel 的开发部署流程从环境准备、项目初始化、编写接口和页面到推送 Git 仓库触发 Vercel 自动构建再到配置环境变量、绑定域名和常见问题排查。你现在应该掌握了以下关键点Next.js 的 App Router 核心概念包括 Server Component、Route Handlers、ISR。Vercel 的两种部署方式和环境变量管理方法。如何根据业务场景选择合适的渲染策略。部署失败时的系统化排查思路。下一步可以继续深入的方向包括接入数据库比如 PostgreSQL 或 MongoDB打通完整的数据链路。学习next-auth实现身份认证。了解 Incremental Static Regeneration 的按需刷新语法。探索 Vercel 的 Serverless Functions 和边缘函数在复杂业务中的应用。部署只是一个开始真正的工程能力在于根据业务场景权衡渲染时机、数据粒度、缓存策略和代码结构。建议你动手把本文的示例部署一次再尝试改造成自己的个人博客或工具站。遇到报错时善用 Vercel 的 Logs 和本地next build输出往往能找到最直接的线索。