27. 构建与部署（上）

构建流程概览

Next.js 的构建命令 next build 会执行以下操作：

1. 代码编译：使用 SWC 编译 TypeScript 和 TSX 代码
2. 代码分割：按路由自动分割代码
3. 静态预渲染：预渲染所有静态页面
4. 类型检查：运行 TypeScript 类型检查（除非禁用）
5. 生成构建产物：输出到 .next 目录

# 标准构建命令
npm run build

# 构建并分析 Bundle
npm run build -- --experimental-build-mode generate

构建完成后，使用 next start 启动生产服务器：

npm start

Next.js 自动优化

Next.js 默认启用了以下优化，无需额外配置：

优化项	说明
Server Components	默认使用，不增加客户端 JS 体积
代码分割	按路由段自动分割
预取	Link 进入视口时自动预取
预渲染	构建时预渲染静态页面
缓存	缓存数据请求、渲染结果、静态资源

开发阶段的优化建议

路由与渲染

• 使用 Layout 共享 UI 并启用部分渲染
• 使用 <Link> 组件进行客户端导航和预取
• 创建自定义错误页面处理异常和 404
• 合理放置 "use client" 边界，避免不必要地增加客户端 JS Bundle
• 注意 cookies()、searchParams 等 API 会将整个路由切换为动态渲染

数据获取与缓存

• 在 Server Components 中直接获取数据
• 使用 Route Handlers 为 Client Components 提供数据
• 使用 Loading UI 和 React Suspense 实现流式传输
• 并行获取数据，减少网络瀑布流
• 使用 public 目录存放静态资源

UI 与可访问性

• 使用 Server Actions 处理表单提交和验证
• 使用 next/font 优化字体加载
• 使用 next/image 优化图片
• 使用 <Script> 组件优化第三方脚本
• 启用 eslint-plugin-jsx-a11y 检查可访问性问题

安全

• 验证每个 Server Action 的认证和授权
• 确保 .env.* 文件已加入 .gitignore
• 考虑添加 Content Security Policy

上线前的检查清单

Core Web Vitals 性能测量

Core Web Vitals 是 Google 定义的网站性能核心指标：

指标	含义	目标值
LCP (Largest Contentful Paint)	最大内容绘制时间	≤ 2.5s
INP (Interaction to Next Paint)	交互到下一次绘制	≤ 200ms
CLS (Cumulative Layout Shift)	累积布局偏移	≤ 0.1

使用 Lighthouse 进行模拟测试：

1. 打开 Chrome DevTools
2. 切换到 Lighthouse 面板
3. 选择 “Performance” 和 “Accessibility”
4. 点击 “Analyze page load”

分析 JavaScript Bundle

使用 @next/bundle-analyzer 分析打包体积：

npm install -D @next/bundle-analyzer

配置 next.config.ts：

// next.config.ts
import type { NextConfig } from 'next'
import bundleAnalyzer from '@next/bundle-analyzer'

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})

const nextConfig: NextConfig = {
  /* 配置选项 */
}

export default withBundleAnalyzer(nextConfig)

运行分析：

ANALYZE=true npm run build

这会打开一个交互式可视化页面，展示各个模块的体积占比，帮助你识别大型依赖。

其他分析工具

工具	用途
Import Cost (VS Code 插件)	实时显示导入的体积
Package Phobia	查看 npm 包的安装体积
Bundle Phobia	查看 npm 包的打包体积
bundlejs	在线打包并分析 npm 包

构建优化技巧

1. 减少客户端 JS 体积

• 尽量使用 Server Components
• 将客户端逻辑下沉到叶子组件
• 使用动态导入延迟加载客户端组件

// 动态导入客户端组件
import dynamic from 'next/dynamic'

const HeavyComponent = dynamic(() => import('@/components/HeavyComponent'), {
  loading: () => <p>加载中...</p>,
  ssr: false, // 如果组件不需要 SSR
})

2. 优化图片使用

import Image from 'next/image'

// 使用 next/image 自动优化
<Image
  src="/hero.jpg"
  alt="Hero"
  width={800}
  height={600}
  preload // 首屏图片优先加载（Next.js 16 用 preload 替代已弃用的 priority）
/>

3. 优化第三方脚本

import Script from 'next/script'

<Script
  src="https://example.com/analytics.js"
  strategy="lazyOnload" // 延迟加载
/>

4. 使用 Suspense 实现流式渲染

import { Suspense } from 'react'

export default function Page() {
  return (
    <div>
      <h1>页面标题</h1>
      <Suspense fallback={<div>加载中...</div>}>
        <AsyncComponent />
      </Suspense>
    </div>
  )
}

构建错误排查

常见构建错误及解决方案：

错误类型	原因	解决方案
TypeScript 错误	类型不匹配	修复类型错误，或临时设置 ignoreBuildErrors: true
ESLint 错误	代码风格问题	Next.js 16 中 next lint 已移除，next build 不再自动执行 lint。需使用 ESLint CLI 或 Biome 直接运行
内存不足	项目过大	增加 Node.js 内存限制：NODE_OPTIONS=--max-old-space-size=4096
超时	静态页面过多	使用 ISR 替代全量静态生成

构建缓存

Next.js 会缓存构建结果以加速后续构建。默认情况下，缓存存储在 .next/cache 目录。

在 CI/CD 环境中，可以缓存 .next/cache 目录以加速构建：

# GitHub Actions 示例
- name: Cache Next.js build
  uses: actions/cache@v3
  with:
    path: .next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/*.ts', '**/*.tsx') }}

生产环境变量

确保生产环境变量正确配置：

# .env.production
DATABASE_URL=postgresql://...
NEXTAUTH_SECRET=your-secret
NEXTAUTH_URL=https://yourdomain.com

小结

这一章我们学了构建和上线前的优化：

1. next build 构建，next start 启动生产服务器
2. 用 @next/bundle-analyzer 分析打包体积
3. 用 Lighthouse 测 Core Web Vitals
4. 尽量用 Server Components，减少客户端 JS
5. 缓存 .next/cache 能加速 CI/CD 构建