Next.js 完全指南专题：从入门到 SaaS 生产实战（2025 App Router） on PlumePHP

Next.js 完全指南 — 第 1 章：Next.js 的出现、背景与核心理念（Part 1）

Sat, 22 Nov 2025 11:00:00 +0800

本章目标

理解现代 Web 为什么越来越复杂

理解 React 为什么需要一个框架

理解 Next.js 出现的根本原因

掌握 Next.js 架构背后的思想

认识 App Router 作为未来标准的原因

1.1 为什么需要 Next.js？——现代 Web 的复杂性远超想象

如果你长期写 React，你一定对以下问题很熟悉：

Next.js 速查表（2025 App Router）：API、配置与决策矩阵

Thu, 20 Nov 2025 12:00:00 +0800

本文是《Next.js 完全指南》系列的速查参考页，适合在开发时快速定位 API 用法和配置选项。如需深入理解，请参考对应章节。

一、文件路由约定

app/
├── page.tsx # / 路由页面
├── layout.tsx # 根布局（包裹所有子路由）
├── loading.tsx # 加载状态（Suspense fallback）
├── error.tsx # 错误边界
├── not-found.tsx # 404 页面
├── template.tsx # 类似 layout 但每次导航重新挂载
├── route.ts # API Route（GET/POST/...）
├── default.tsx # 并行路由默认 fallback
├── global-error.tsx # 全局错误处理（根 layout error）
│
├── blog/
│ ├── page.tsx # /blog
│ ├── layout.tsx # /blog/* 的布局
│ └── [slug]/
│ ├── page.tsx # /blog/:slug
│ ├── loading.tsx
│ └── error.tsx
│
├── (marketing)/ # Route Group（无 URL 前缀）
│ ├── about/
│ │ └── page.tsx # /about
│ └── pricing/
│ └── page.tsx # /pricing
│
├── [locale]/ # 动态段：/en, /zh
│ └── [...catchAll]/ # 捕获所有：/anything/here
│ └── page.tsx

文件	作用域	备注
`page.tsx`	当前路由	唯一必需文件
`layout.tsx`	当前路由及子路由	导航时保持状态
`template.tsx`	当前路由及子路由	导航时重新挂载
`loading.tsx`	当前路由及子路由	Suspense fallback
`error.tsx`	当前路由及子路由	错误边界
`not-found.tsx`	当前路由	404 或 notFound() 触发
`route.ts`	当前路由	API endpoint

二、渲染模式决策树

页面需要动态数据？
 ├── 否 → 数据是否可能变化？
 │ ├── 否 → export const dynamicParams = false;
 │ │ # SSG（构建时生成，永不更新）
 │ └── 是 → export const revalidate = 3600;
 │ # ISR（增量静态再生）
 └── 是 → 数据是否用户相关/实时？
 ├── 是 → export const dynamic = 'force-dynamic';
 │ # SSR（每次请求实时渲染）
 └── 否 → export const revalidate = 60;
 # ISR（定期更新 + 按需失效）

需要流式加载？
 └── 部分组件用 Suspense + loading.tsx
 # Streaming（渐进式渲染，先骨架后内容）

只有前端交互？
 └── page.tsx 中不需要 async
 # CSR（纯客户端渲染，"use client" 组件）

模式	首次访问	缓存	数据新鲜度	适用	配置
SSG	构建时	CDN 永久	永不更新	法律页/关于	默认（无 async fetch）
ISR	首次访问生成	CDN + TTL	TTL 后后台更新	博客/商品页	`revalidate = N`
SSR	每次请求	无	最新	用户中心/搜索	`dynamic = 'force-dynamic'`
Streaming	渐进式	部分缓存	流内实时	大数据量页	Suspense + loading.tsx
CSR	客户端渲染	浏览器	客户端实时	后台管理	`"use client"`

三、fetch 与缓存

// 默认行为（Next.js 15）：请求记忆 + 数据缓存
fetch('https://api.example.com/data');

// 完全禁用缓存（类似 SSR）
fetch('https://api.example.com/data', { cache: 'no-store' });

// ISR：缓存 1 小时后后台刷新
fetch('https://api.example.com/data', { next: { revalidate: 3600 } });

// 带标签缓存（支持按需失效）
fetch('https://api.example.com/posts', { next: { tags: ['posts'] } });

// 永久缓存（类似 SSG）
fetch('https://api.example.com/static', { cache: 'force-cache' });

// 页面级别缓存控制
export const revalidate = 60; // ISR 60 秒
export const dynamic = 'force-dynamic'; // SSR（无缓存）
export const dynamicParams = false; // 只预生成已知路径

四、Server Actions

// 定义 Server Action（可直接绑定到 <form>）
async function createPost(formData: FormData) {
 'use server';
 const title = formData.get('title') as string;
 await prisma.post.create({ data: { title } });
 revalidatePath('/posts');
}

// 带错误处理和返回值的 Server Action
async function submitContact(formData: FormData) {
 'use server';
 const email = formData.get('email') as string;

 if (!email.includes('@')) {
 return { error: 'Invalid email' };
 }

 try {
 await sendEmail(email);
 return { success: true };
 } catch {
 return { error: 'Failed to send' };
 }
}

// 前端：用 useFormState 处理返回
'use client';
import { useFormState } from 'react-dom';

export default function ContactForm() {
 const [state, formAction] = useFormState(submitContact, { error: null });

 return (
 <form action={formAction}>
 <input name="email" type="email" required />
 <button type="submit">Send</button>
 {state?.error && <p>{state.error}</p>}
 {state?.success && <p>Sent!</p>}
 </form>
 );
}

// useOptimistic：乐观更新
const [optimisticState, addOptimistic] = useOptimistic(
 initialState,
 (current, newItem) => [...current, newItem]
);

async function handleSubmit(formData: FormData) {
 addOptimistic({ id: 'temp', title: formData.get('title') });
 await serverAction(formData);
}

五、Metadata API

// page.tsx / layout.tsx
import { Metadata } from 'next';

export const metadata: Metadata = {
 title: 'My Page',
 description: 'Page description for SEO',

 openGraph: {
 title: 'My Page',
 description: 'OG description',
 images: ['/og-image.jpg'],
 },

 twitter: {
 card: 'summary_large_image',
 title: 'My Page',
 images: ['/twitter-image.jpg'],
 },

 robots: {
 index: true,
 follow: true,
 },

 alternates: {
 canonical: 'https://example.com/page',
 languages: {
 'en-US': '/en/page',
 'zh-CN': '/zh/page',
 },
 },
};

// 动态 Metadata（基于路由参数）
export async function generateMetadata({ params }): Promise<Metadata> {
 const post = await getPost(params.slug);
 return {
 title: post.title,
 description: post.excerpt,
 };
}

六、Error 处理

// app/error.tsx（局部错误边界）
'use client';

export default function Error({ error, reset }: {
 error: Error & { digest?: string };
 reset: () => void;
}) {
 return (
 <div>
 <h2>Something went wrong</h2>
 <p>{error.message}</p>
 <button onClick={reset}>Try again</button>
 </div>
 );
}

// app/global-error.tsx（全局错误）
'use client';

export default function GlobalError({ error, reset }) {
 return (
 <html>
 <body>
 <h2>Global Error</h2>
 <button onClick={reset}>Reload</button>
 </body>
 </html>
 );
}

// 主动抛出 404
import { notFound } from 'next/navigation';

export default async function Page({ params }) {
 const post = await getPost(params.slug);
 if (!post) notFound(); // 渲染 not-found.tsx
 return <Post post={post} />;
}

七、Middleware

// middleware.ts（项目根目录）
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
 const { pathname } = request.nextUrl;

 // 认证检查
 const token = request.cookies.get('token')?.value;
 if (!token && pathname.startsWith('/dashboard')) {
 return NextResponse.redirect(new URL('/login', request.url));
 }

 // i18n 重定向
 if (!pathname.startsWith('/en') && !pathname.startsWith('/zh')) {
 return NextResponse.redirect(new URL('/en' + pathname, request.url));
 }

 // URL 重写（URL 不变，内部路由改变）
 if (pathname === '/docs') {
 return NextResponse.rewrite(new URL('/documentation', request.url));
 }

 // 注入请求头
 const headers = new Headers(request.headers);
 headers.set('x-user-country', request.geo?.country || 'US');
 return NextResponse.next({ request: { headers } });
}

// 匹配规则
export const config = {
 matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

八、next.config.js / next.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
 // 独立运行模式（Docker 必需）
 output: 'standalone',

 // 图片配置
 images: {
 domains: ['cdn.example.com'],
 remotePatterns: [
 { protocol: 'https', hostname: '**.example.com' },
 ],
 formats: ['image/avif', 'image/webp'],
 },

 // 重写规则
 async rewrites() {
 return [
 { source: '/old-path', destination: '/new-path' },
 { source: '/api/:path*', destination: 'https://api.example.com/:path*' },
 ];
 },

 // 重定向
 async redirects() {
 return [
 { source: '/about-us', destination: '/about', permanent: true },
 ];
 },

 // 请求头
 async headers() {
 return [
 {
 source: '/:path*',
 headers: [
 { key: 'X-Frame-Options', value: 'DENY' },
 ],
 },
 ];
 },

 // TypeScript/ESLint 构建时检查（临时禁用）
 typescript: { ignoreBuildErrors: false },
 eslint: { ignoreDuringBuilds: false },

 // 实验性功能
 experimental: {
 ppr: true, // 部分预渲染
 dynamicIO: true, // 动态 IO（Next.js 15+）
 after: true, // after() API
 },
};

export default nextConfig;

九、Server/Client 组件边界速查

能力	Server Component	Client Component
async/await	✅	❌（需用 useEffect + useState）
访问数据库/ORM	✅	❌（通过 API 或 props）
访问 `fs` / `path`	✅	❌
`headers()` / `cookies()`	✅	❌（通过 API）
`useState` / `useEffect`	❌	✅
`onClick` / `onChange`	❌	✅
`window` / `document`	❌	✅
`localStorage`	❌	✅
第三方库（Framer Motion）	部分✅	✅

十、CLI 命令速查

# 创建项目
npx create-next-app@latest my-app --typescript --tailwind --app

# 开发
npm run dev # 启动开发服务器（默认 Turbopack）
npm run dev --turbo # 显式启用 Turbopack

# 构建
npm run build # 生产构建
npm start # 启动生产服务器（需先 build）

# 分析 Bundle
npm install @next/bundle-analyzer
# next.config.js: ANALYZE=true npm run build

# 类型检查
npx tsc --noEmit

Next.js 常见问题 FAQ（2025）：App Router / Server Components / 渲染策略 50+ 问答

Thu, 20 Nov 2025 11:00:00 +0800

本文是《Next.js 完全指南》系列的 FAQ 补充，覆盖从入门到生产中最常遇到的 50+ 个问题。按主题分组，建议结合 Ctrl+F 快速定位。如果想系统学习，请参考 Next.js 完全指南专题。

第 7 章：Next.js 数据获取体系

Sun, 16 Nov 2025 01:07:31 +0800

本章是卷 III 的开篇章节。读完本章，你将深入理解 Next.js 的数据获取体系，掌握 fetch 扩展机制、缓存策略和 revalidate 机制，能够设计高性能的数据流架构。

7.1 fetch 的扩展机制

Next.js 对 fetch 的增强

Next.js 扩展了原生的 fetch API，添加了缓存、标签和 revalidate 功能。

第 6 章：Client Components 与浏览器端交互

Sun, 16 Nov 2025 01:06:31 +0800

本章是卷 II 的收尾章节。读完本章，你将掌握 Client Components 的正确使用方式，理解如何在 Server Components 和 Client Components 之间做出最佳选择。

6.1 “use client” 声明规则与边界划分

什么是 “use client”

"use client" 是一个指令声明，用于标记一个文件及其所有导入为 Client Component。

第 5 章：React Server Components 深入解析

Sun, 16 Nov 2025 01:05:31 +0800

本章是 RSC 的深度解析章节。读完本章，你将掌握 React Server Components 的内部工作原理，理解多层缓存系统，并能够在生产环境中正确使用 RSC。

5.1 Server Components 的设计动机

传统 React 应用的痛点

在理解 RSC 之前，先看看传统 React 应用面临的问题。

第 4 章：现代 Web 渲染模型全景

Sun, 16 Nov 2025 01:04:31 +0800

本章是卷 II 的开篇章节。读完本章，你将建立完整的渲染模型心智地图，理解每种渲染策略的工作原理、优缺点和适用场景。

4.1 CSR 的局限性

什么是 CSR（Client-Side Rendering）

CSR（客户端渲染） 是传统 React SPA 的渲染方式：

第 3 章：App Router 目录结构全解构

Sun, 16 Nov 2025 01:03:31 +0800

本章是 App Router 的核心章节。读完本章，你将深入理解 app/ 目录的设计哲学，掌握所有路由模式和特殊文件的使用方式。

3.1 app/ 目录的设计理念与文件系统路由

文件系统路由：文件即路由

App Router 的核心理念是 文件系统路由（File-system Routing）：目录结构就是路由结构。

第 2 章：快速上手 — 创建你的第一个 Next.js 项目

Sun, 16 Nov 2025 01:02:31 +0800

本章是实战章节。读完本章，你将完成一个包含页面、API、TailwindCSS 样式的完整 Next.js 项目，并成功部署到 Vercel。

2.1 使用 create-next-app 初始化项目

前置要求

在开始之前，确保你的开发环境满足以下要求：

Next.js 完全指南：从入门到 SaaS 生产实战（2025 App Router）

Sun, 16 Nov 2025 01:01:31 +0800

本系列文章是面向中高级前端与全栈开发者的 Next.js 15 App Router 系统化教程，从框架核心理念讲起，逐步深入到 React Server Components、Server Actions、数据库集成、认证鉴权，最终落地到多租户 SaaS 生产级架构与多平台部署。无论你是从 React SPA 迁移，还是从零构建全栈产品，这份指南都提供了可直接复用的工程实践与架构决策参考。

第 1 章：Next.js 简介与核心理念

Sun, 16 Nov 2025 01:01:31 +0800

本章是《Next.js 完全指南》系列的开篇章节。读完本章，你将建立对 Next.js 的系统性认知：它为什么存在、它解决了什么问题、它如何演进、以及为什么 2025 年的新项目应该选择 App Router。

Next.js 介绍

Sun, 16 Nov 2025 01:00:31 +0800

一、Next.js 是什么？

定位：基于 React 的全栈 Web 框架，用来构建从简单博客到复杂 SaaS 的各种 Web 应用。
作者&公司：由 Vercel 公司及社区维护，最初由 Guillermo Rauch 等人创建。(维基百科)

第 18 章：SEO 深度优化（Metadata API 与结构化数据）

Wed, 11 Jun 2025 00:00:00 +0000

本章目标：构建一套完整的 Next.js SEO 工程体系——从 Metadata API 的三种使用模式、动态 OG 图片生成、Sitemap / robots.txt 配置，到结构化数据、国际化 SEO 与搜索引擎监控，让你的站点在搜索引擎中获得最佳排名。

第 19 章：测试体系（Vitest + RTL + Playwright）

Wed, 11 Jun 2025 00:00:00 +0000

本章目标：建立 Next.js App Router 的完整测试体系——使用 Vitest 做单元测试、React Testing Library 做组件测试、MSW 做 API Mock、Playwright 做 E2E 测试，并配置覆盖率、CI 集成与测试最佳实践。

第 20 章：错误处理与监控（Sentry 与可观测性）

Wed, 11 Jun 2025 00:00:00 +0000

本章目标：建立一套完整的错误处理与监控体系——理解 Next.js App Router 中错误边界的层次结构，掌握 Server Component / Client Component / Server Action / Route Handler 各自的错误处理策略，并集成 Sentry 实现生产环境的实时监控与告警。

第 21 章：Docker 部署与 CI/CD 流水线

Wed, 11 Jun 2025 00:00:00 +0000

本章目标：掌握 Next.js 生产部署的完整技术栈——理解 Standalone Output 模式、构建优化后的 Docker 镜像、配置 GitHub Actions 自动化流水线，并了解 Vercel / Docker / Kubernetes 多种部署方案的取舍。

21.1 部署方案对比

主流部署平台

平台	类型	适用场景	复杂度	成本
Vercel	Serverless	快速上线、Next.js 官方推荐	低	按用量付费
Netlify	Serverless	静态站点为主	低	免费层 + 付费
Docker 自托管	容器	私有部署、合规要求	中	服务器成本
Kubernetes	容器编排	大规模、高可用	高	集群成本
Cloudflare Pages	Edge	全球加速、低延迟	低	免费层优厚
Render	PaaS	全栈应用	低	月付固定价
Railway	PaaS	快速部署 + 数据库	低	按用量
AWS ECS	容器服务	AWS 生态	中	按用量

选型决策树

你的需求...
├── 快速上线 + Next.js 最佳体验 → ✅ Vercel
├── 数据合规 / 私有部署 → ✅ Docker 自托管
├── 全球边缘加速 → ✅ Cloudflare Pages / Vercel Edge
├── 已有 K8s 集群 → ✅ Kubernetes + Helm
├── 预算有限 + 全栈应用 → ✅ Render / Railway
└── 已有 AWS / GCP / Azure → 对应云服务的容器方案

21.2 Next.js Standalone Output

启用 Standalone 模式

// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
 output: 'standalone', // 启用独立部署包

 // 可选：自定义 server 配置
 // serverExternalPackages: ['sharp', 'bcrypt'],
};

module.exports = nextConfig;

Standalone 输出结构

npm run build

.next/
├── standalone/ # 独立部署包（仅包含必要依赖）
│ ├── node_modules/ # 精简的 node_modules
│ ├── public/ # 静态资源
│ ├── .next/ # 构建产物
│ └── server.js # 启动脚本
├── static/ # 静态文件（需要复制到 standalone）
└── cache/ # 构建缓存

为什么使用 Standalone？

传统部署：
 - 需要完整 node_modules（通常 200-500MB）
 - 启动慢、镜像大
 - 依赖 npm install

Standalone 部署：
 - 仅包含运行必需的依赖（通常 30-80MB）
 - 启动快、镜像小
 - 不需要 npm install
 - 适合 Docker、Serverless

21.3 Docker 多阶段构建

完整 Dockerfile

# Dockerfile

# ============ 阶段 1：依赖安装 ============
FROM node:20-alpine AS base
RUN apk add --no-cache libc6-compat
WORKDIR /app

# ============ 阶段 2：安装依赖 ============
FROM base AS deps
COPY package.json package-lock.json* ./
COPY prisma ./prisma/

# 安装生产依赖（用于生成 Prisma Client）
RUN npm ci --omit=dev

# 生成 Prisma Client
RUN npx prisma generate

# 重新安装所有依赖（包括 dev，用于构建）
RUN npm ci

# ============ 阶段 3：构建 ============
FROM base AS builder

# 复制依赖和 Prisma Client
COPY --from=deps /app/node_modules ./node_modules
COPY --from=deps /app/.prisma ./.prisma

COPY . .

# 设置构建时环境变量
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production

# 构建 Next.js 应用
RUN npm run build

# ============ 阶段 4：生产运行 ============
FROM base AS runner

WORKDIR /app

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1

# 创建非 root 用户
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# 复制静态资源
COPY --from=builder /app/public ./public

# 复制 standalone 输出
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

# 复制 Prisma 相关文件（用于运行时迁移）
COPY --from=builder --chown=nextjs:nodejs /app/prisma ./prisma
COPY --from=builder --chown=nextjs:nodejs /app/node_modules/.prisma ./node_modules/.prisma
COPY --from=builder --chown=nextjs:nodejs /app/node_modules/@prisma ./node_modules/@prisma

# 切换到非 root 用户
USER nextjs

# 暴露端口
EXPOSE 3000

# 配置环境变量
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
 CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

# 启动命令（包含数据库迁移）
CMD ["sh", "-c", "npx prisma migrate deploy && node server.js"]

.dockerignore

# .dockerignore

Dockerfile
.dockerignore
node_modules
npm-debug.log
.next
.git
.gitignore
README.md
.env
.env.local
.env.*.local
.vscode
.idea
coverage
playwright-report
test-results
*.md
!README.md

构建与运行

# 构建镜像
docker build -t my-blog:latest .

# 查看镜像大小
docker images my-blog
# REPOSITORY TAG IMAGE ID CREATED SIZE
# my-blog latest abc123 2 minutes ago 180MB

# 运行容器
docker run -d \
 -p 3000:3000 \
 --env-file .env.production \
 --name my-blog \
 my-blog:latest

# 查看日志
docker logs -f my-blog

# 停止容器
docker stop my-blog
docker rm my-blog

多阶段构建优化

优化技巧：

1. 使用 Alpine 基础镜像（5MB vs 900MB）
2. 多阶段构建（构建阶段 + 运行阶段分离）
3. 复制 standalone 而非完整 node_modules
4. 使用 npm ci 而非 npm install
5. 缓存 Prisma Client 生成
6. 非 root 用户运行（安全）
7. 健康检查端点（监控）

镜像大小对比：
- 传统方式：~800MB
- Standalone + Alpine：~150-200MB
- 进一步压缩（distroless）：~120MB

21.4 Docker Compose 本地开发

完整开发环境

# docker-compose.yml

version: '3.9'

services:
 # Next.js 应用
 app:
 build:
 context: .
 dockerfile: Dockerfile
 ports:
 - '3000:3000'
 environment:
 - NODE_ENV=production
 - DATABASE_URL=postgresql://postgres:postgres@db:5432/myblog
 - REDIS_URL=redis://redis:6379
 depends_on:
 db:
 condition: service_healthy
 redis:
 condition: service_started
 restart: unless-stopped
 networks:
 - app-network

 # PostgreSQL 数据库
 db:
 image: postgres:16-alpine
 environment:
 POSTGRES_USER: postgres
 POSTGRES_PASSWORD: postgres
 POSTGRES_DB: myblog
 ports:
 - '5432:5432'
 volumes:
 - postgres_data:/var/lib/postgresql/data
 healthcheck:
 test: ['CMD-SHELL', 'pg_isready -U postgres']
 interval: 10s
 timeout: 5s
 retries: 5
 networks:
 - app-network

 # Redis 缓存
 redis:
 image: redis:7-alpine
 ports:
 - '6379:6379'
 volumes:
 - redis_data:/data
 networks:
 - app-network

 # Nginx 反向代理（可选）
 nginx:
 image: nginx:alpine
 ports:
 - '80:80'
 - '443:443'
 volumes:
 - ./nginx.conf:/etc/nginx/nginx.conf:ro
 - ./ssl:/etc/nginx/ssl:ro
 depends_on:
 - app
 networks:
 - app-network

volumes:
 postgres_data:
 redis_data:

networks:
 app-network:
 driver: bridge

开发环境 Docker Compose

# docker-compose.dev.yml

version: '3.9'

services:
 app:
 build:
 context: .
 dockerfile: Dockerfile.dev
 ports:
 - '3000:3000'
 environment:
 - NODE_ENV=development
 volumes:
 - .:/app
 - /app/node_modules
 - /app/.next
 command: npm run dev
 depends_on:
 - db
 - redis

 db:
 image: postgres:16-alpine
 environment:
 POSTGRES_USER: postgres
 POSTGRES_PASSWORD: postgres
 POSTGRES_DB: myblog_dev
 ports:
 - '5432:5432'
 volumes:
 - postgres_dev_data:/var/lib/postgresql/data

 redis:
 image: redis:7-alpine
 ports:
 - '6379:6379'

volumes:
 postgres_dev_data:

使用方式

# 生产环境
docker-compose up -d
docker-compose down
docker-compose logs -f app

# 开发环境
docker-compose -f docker-compose.dev.yml up
docker-compose -f docker-compose.dev.yml down

21.5 GitHub Actions CI/CD

完整 CI/CD 流水线

# .github/workflows/ci.yml

name: CI

on:
 push:
 branches: [main, develop]
 pull_request:
 branches: [main]

jobs:
 # ============ 代码质量检查 ============
 lint:
 name: Lint & Type Check
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - uses: actions/setup-node@v4
 with:
 node-version: 20
 cache: 'npm'

 - run: npm ci

 - name: ESLint
 run: npm run lint

 - name: TypeScript
 run: npm run type-check

 - name: Prettier
 run: npm run format:check

 # ============ 单元测试 ============
 test:
 name: Unit Tests
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - uses: actions/setup-node@v4
 with:
 node-version: 20
 cache: 'npm'

 - run: npm ci
 - run: npm run test:run

 - name: Upload coverage
 uses: codecov/codecov-action@v4
 with:
 files: ./coverage/lcov.info
 token: ${{ secrets.CODECOV_TOKEN }}

 # ============ E2E 测试 ============
 e2e:
 name: E2E Tests
 runs-on: ubuntu-latest
 needs: [lint, test]
 steps:
 - uses: actions/checkout@v4

 - uses: actions/setup-node@v4
 with:
 node-version: 20
 cache: 'npm'

 - run: npm ci
 - run: npx playwright install --with-deps chromium

 - name: Start PostgreSQL
 run: |
 docker run -d \
 --name postgres \
 -e POSTGRES_USER=postgres \
 -e POSTGRES_PASSWORD=postgres \
 -e POSTGRES_DB=test_db \
 -p 5432:5432 \
 postgres:16-alpine

 - name: Wait for PostgreSQL
 run: |
 until pg_isready -h localhost -p 5432 -U postgres; do
 sleep 2
 done

 - name: Run migrations
 env:
 DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
 run: npx prisma migrate deploy

 - name: Seed test data
 env:
 DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
 run: npx prisma db seed

 - name: Run E2E tests
 env:
 DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
 NEXTAUTH_SECRET: test-secret
 NEXTAUTH_URL: http://localhost:3000
 run: npm run test:e2e

 - name: Upload test artifacts
 uses: actions/upload-artifact@v4
 if: failure()
 with:
 name: playwright-report
 path: playwright-report/
 retention-days: 7

 # ============ 构建检查 ============
 build:
 name: Build
 runs-on: ubuntu-latest
 needs: [lint, test]
 steps:
 - uses: actions/checkout@v4

 - uses: actions/setup-node@v4
 with:
 node-version: 20
 cache: 'npm'

 - run: npm ci

 - name: Generate Prisma Client
 run: npx prisma generate

 - name: Build Next.js
 env:
 NEXT_TELEMETRY_DISABLED: 1
 run: npm run build

 - name: Upload build artifacts
 uses: actions/upload-artifact@v4
 with:
 name: next-build
 path: |
 .next/standalone
 .next/static
 public
 retention-days: 1

CD 流水线（部署到 Docker Registry）

# .github/workflows/deploy.yml

name: Deploy

on:
 push:
 branches: [main]
 tags: ['v*']

env:
 REGISTRY: ghcr.io
 IMAGE_NAME: ${{ github.repository }}

jobs:
 # ============ 构建并推送 Docker 镜像 ============
 build-and-push:
 name: Build & Push Docker Image
 runs-on: ubuntu-latest
 permissions:
 contents: read
 packages: write

 steps:
 - uses: actions/checkout@v4

 - name: Set up Docker Buildx
 uses: docker/setup-buildx-action@v3

 - name: Log in to GitHub Container Registry
 uses: docker/login-action@v3
 with:
 registry: ${{ env.REGISTRY }}
 username: ${{ github.actor }}
 password: ${{ secrets.GITHUB_TOKEN }}

 - name: Extract metadata
 id: meta
 uses: docker/metadata-action@v5
 with:
 images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
 tags: |
 type=ref,event=branch
 type=semver,pattern={{version}}
 type=semver,pattern={{major}}.{{minor}}
 type=sha,prefix=

 - name: Build and push Docker image
 uses: docker/build-push-action@v5
 with:
 context: .
 push: true
 tags: ${{ steps.meta.outputs.tags }}
 labels: ${{ steps.meta.outputs.labels }}
 cache-from: type=gha
 cache-to: type=gha,mode=max
 platforms: linux/amd64,linux/arm64

 # ============ 部署到生产环境 ============
 deploy-production:
 name: Deploy to Production
 runs-on: ubuntu-latest
 needs: build-and-push
 if: startsWith(github.ref, 'refs/tags/v')
 environment:
 name: production
 url: https://example.com

 steps:
 - name: Deploy via SSH
 uses: appleboy/ssh-action@v1.0.0
 with:
 host: ${{ secrets.PRODUCTION_HOST }}
 username: ${{ secrets.PRODUCTION_USER }}
 key: ${{ secrets.PRODUCTION_SSH_KEY }}
 script: |
 cd /opt/my-blog
 docker-compose pull
 docker-compose up -d --remove-orphans
 docker image prune -f

 - name: Verify deployment
 run: |
 sleep 10
 curl -f https://example.com/api/health || exit 1

 - name: Notify Slack
 if: always()
 uses: 8398a7/action-slack@v3
 with:
 status: ${{ job.status }}
 text: 'Production deployment ${{ job.status }}'
 webhook_url: ${{ secrets.SLACK_WEBHOOK }}

部署到 Vercel

# .github/workflows/deploy-vercel.yml

name: Deploy to Vercel

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 deploy:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: 20

 - name: Install Vercel CLI
 run: npm install -g vercel

 - name: Pull Vercel Environment
 run: vercel pull --yes --environment=${{ github.ref == 'refs/heads/main' && 'production' || 'preview' }} --token=${{ secrets.VERCEL_TOKEN }}

 - name: Build
 run: vercel build ${{ github.ref == 'refs/heads/main' && '--prod' || '' }} --token=${{ secrets.VERCEL_TOKEN }}

 - name: Deploy
 id: deploy
 run: |
 url=$(vercel deploy --prebuilt ${{ github.ref == 'refs/heads/main' && '--prod' || '' }} --token=${{ secrets.VERCEL_TOKEN }})
 echo "url=$url" >> $GITHUB_OUTPUT

 - name: Comment PR
 if: github.event_name == 'pull_request'
 uses: thollander/actions-comment-pull-request@v2
 with:
 message: |
 🚀 Preview deployed to ${{ steps.deploy.outputs.url }}

21.6 Nginx 反向代理配置

基础配置

# nginx.conf

upstream nextjs_app {
 server app:3000;
 keepalive 64;
}

# HTTP 重定向到 HTTPS
server {
 listen 80;
 server_name example.com www.example.com;
 return 301 https://$host$request_uri;
}

# HTTPS 主配置
server {
 listen 443 ssl http2;
 server_name example.com www.example.com;

 # SSL 证书
 ssl_certificate /etc/nginx/ssl/fullchain.pem;
 ssl_certificate_key /etc/nginx/ssl/privkey.pem;
 ssl_protocols TLSv1.2 TLSv1.3;
 ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
 ssl_prefer_server_ciphers off;

 # SSL 会话缓存
 ssl_session_cache shared:SSL:10m;
 ssl_session_timeout 1d;
 ssl_session_tickets off;

 # HSTS
 add_header Strict-Transport-Security "max-age=63072000" always;

 # Gzip 压缩
 gzip on;
 gzip_vary on;
 gzip_comp_level 6;
 gzip_types
 text/plain
 text/css
 text/xml
 text/javascript
 application/json
 application/javascript
 application/xml
 application/rss+xml
 image/svg+xml;

 # 静态资源（Next.js 构建产物，永久缓存）
 location /_next/static/ {
 proxy_pass http://nextjs_app;
 proxy_cache_valid 200 365d;
 add_header Cache-Control "public, max-age=31536000, immutable";
 }

 # 公共资源（手动管理的静态文件）
 location /public/ {
 proxy_pass http://nextjs_app;
 proxy_cache_valid 200 1d;
 add_header Cache-Control "public, max-age=86400";
 }

 # API 路由（不缓存）
 location /api/ {
 proxy_pass http://nextjs_app;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection 'upgrade';
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_cache_bypass $http_upgrade;
 add_header Cache-Control "no-store";
 }

 # 默认路由（Next.js 处理）
 location / {
 proxy_pass http://nextjs_app;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection 'upgrade';
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_cache_bypass $http_upgrade;
 }

 # 健康检查
 location /api/health {
 proxy_pass http://nextjs_app;
 access_log off;
 }

 # 阻止访问敏感文件
 location ~ /\. {
 deny all;
 }

 location ~* \.(env|git|gitignore|dockerignore)$ {
 deny all;
 }
}

Let’s Encrypt SSL

# 安装 Certbot
apt-get install certbot python3-certbot-nginx

# 申请证书
certbot --nginx -d example.com -d www.example.com

# 自动续期
certbot renew --dry-run

21.7 Kubernetes 部署

Deployment 配置

# k8s/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
 name: my-blog
 labels:
 app: my-blog
spec:
 replicas: 3
 selector:
 matchLabels:
 app: my-blog
 strategy:
 type: RollingUpdate
 rollingUpdate:
 maxSurge: 1
 maxUnavailable: 0
 template:
 metadata:
 labels:
 app: my-blog
 spec:
 containers:
 - name: my-blog
 image: ghcr.io/username/my-blog:latest
 imagePullPolicy: Always
 ports:
 - containerPort: 3000
 name: http
 env:
 - name: NODE_ENV
 value: production
 - name: DATABASE_URL
 valueFrom:
 secretKeyRef:
 name: my-blog-secrets
 key: database-url
 - name: NEXTAUTH_SECRET
 valueFrom:
 secretKeyRef:
 name: my-blog-secrets
 key: nextauth-secret
 resources:
 requests:
 memory: '256Mi'
 cpu: '250m'
 limits:
 memory: '512Mi'
 cpu: '500m'
 livenessProbe:
 httpGet:
 path: /api/health
 port: 3000
 initialDelaySeconds: 30
 periodSeconds: 30
 timeoutSeconds: 10
 failureThreshold: 3
 readinessProbe:
 httpGet:
 path: /api/health
 port: 3000
 initialDelaySeconds: 10
 periodSeconds: 10
 timeoutSeconds: 5
 failureThreshold: 3
 imagePullSecrets:
 - name: ghcr-secret

Service 配置

# k8s/service.yaml

apiVersion: v1
kind: Service
metadata:
 name: my-blog
 labels:
 app: my-blog
spec:
 type: ClusterIP
 ports:
 - port: 80
 targetPort: 3000
 protocol: TCP
 name: http
 selector:
 app: my-blog

Ingress 配置

# k8s/ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: my-blog
 annotations:
 cert-manager.io/cluster-issuer: letsencrypt-prod
 nginx.ingress.kubernetes.io/proxy-body-size: '50m'
 nginx.ingress.kubernetes.io/ssl-redirect: 'true'
spec:
 ingressClassName: nginx
 tls:
 - hosts:
 - example.com
 - www.example.com
 secretName: my-blog-tls
 rules:
 - host: example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: my-blog
 port:
 number: 80
 - host: www.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: my-blog
 port:
 number: 80

Helm Chart（可选）

# helm/my-blog/values.yaml

replicaCount: 3

image:
 repository: ghcr.io/username/my-blog
 tag: latest
 pullPolicy: Always

service:
 type: ClusterIP
 port: 80

ingress:
 enabled: true
 className: nginx
 hosts:
 - host: example.com
 paths:
 - path: /
 pathType: Prefix
 tls:
 - secretName: my-blog-tls
 hosts:
 - example.com

resources:
 limits:
 cpu: 500m
 memory: 512Mi
 requests:
 cpu: 250m
 memory: 256Mi

autoscaling:
 enabled: true
 minReplicas: 3
 maxReplicas: 10
 targetCPUUtilizationPercentage: 70

env:
 NODE_ENV: production

secrets:
 database-url: ""
 nextauth-secret: ""

部署命令

# 创建命名空间
kubectl create namespace my-blog

# 创建 Secret
kubectl create secret generic my-blog-secrets \
 --from-literal=database-url="postgresql://..." \
 --from-literal=nextauth-secret="your-secret" \
 -n my-blog

# 应用配置
kubectl apply -f k8s/ -n my-blog

# 或使用 Helm
helm install my-blog ./helm/my-blog -n my-blog

# 查看状态
kubectl get pods -n my-blog
kubectl get svc -n my-blog
kubectl get ingress -n my-blog

# 查看日志
kubectl logs -f deployment/my-blog -n my-blog

# 滚动更新
kubectl set image deployment/my-blog my-blog=ghcr.io/username/my-blog:v2 -n my-blog

21.8 蓝绿部署与金丝雀发布

蓝绿部署脚本

#!/bin/bash
# scripts/blue-green-deploy.sh

set -e

BLUE_DEPLOYMENT="my-blog-blue"
GREEN_DEPLOYMENT="my-blog-green"
SERVICE="my-blog"
NEW_IMAGE=$1

# 检查当前活跃的颜色
ACTIVE_COLOR=$(kubectl get svc $SERVICE -o jsonpath='{.spec.selector.color}')

if [ "$ACTIVE_COLOR" == "blue" ]; then
 NEW_COLOR="green"
 NEW_DEPLOYMENT=$GREEN_DEPLOYMENT
else
 NEW_COLOR="blue"
 NEW_DEPLOYMENT=$BLUE_DEPLOYMENT
fi

echo "Active color: $ACTIVE_COLOR"
echo "Deploying to: $NEW_COLOR"

# 更新非活跃 deployment 的镜像
kubectl set image deployment/$NEW_DEPLOYMENT my-blog=$NEW_IMAGE

# 等待新 deployment 就绪
kubectl rollout status deployment/$NEW_DEPLOYMENT

# 健康检查
echo "Running health check on new deployment..."
kubectl exec deployment/$NEW_DEPLOYMENT -- curl -f http://localhost:3000/api/health

# 切换流量
echo "Switching traffic to $NEW_COLOR..."
kubectl patch svc $SERVICE -p "{\"spec\":{\"selector\":{\"color\":\"$NEW_COLOR\"}}}"

echo "Deployment complete! $NEW_COLOR is now active."
echo "To rollback, run: kubectl patch svc $SERVICE -p '{\"spec\":{\"selector\":{\"color\":\"$ACTIVE_COLOR\"}}}'"

金丝雀发布（Argo Rollouts）

# k8s/rollout.yaml

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
 name: my-blog
spec:
 replicas: 10
 strategy:
 canary:
 steps:
 - setWeight: 10 # 10% 流量到新镜像
 - pause: { duration: 5m }  # 观察 5 分钟
 - setWeight: 30 # 30% 流量
 - pause: { duration: 5m }
 - setWeight: 60 # 60% 流量
 - pause: { duration: 5m }
 - setWeight: 100 # 100% 流量
 analysis:
 templates:
 - templateName: success-rate
 startingStep: 1
 selector:
 matchLabels:
 app: my-blog
 template:
 metadata:
 labels:
 app: my-blog
 spec:
 containers:
 - name: my-blog
 image: ghcr.io/username/my-blog:latest
 ports:
 - containerPort: 3000

21.9 环境变量管理

环境分类

# .env.example（示例，提交到 git）
DATABASE_URL="postgresql://user:pass@localhost:5432/myblog"
NEXTAUTH_SECRET="your-secret-here"
NEXTAUTH_URL="http://localhost:3000"

# .env.local（本地开发，不提交）
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/myblog_dev"
NEXTAUTH_SECRET="dev-secret"

# .env.production（生产环境，不提交）
DATABASE_URL="postgresql://prod_user:prod_pass@db.example.com:5432/myblog"
NEXTAUTH_SECRET="prod-secret-very-long-and-random"
NEXTAUTH_URL="https://example.com"

使用 GitHub Secrets

# .github/workflows/deploy.yml

env:
 DATABASE_URL: ${{ secrets.DATABASE_URL }}
 NEXTAUTH_SECRET: ${{ secrets.NEXTAUTH_SECRET }}
 SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}

使用 Vault（生产环境）

# 安装 Vault CLI
brew install vault

# 登录
vault login

# 读取 secrets
export DATABASE_URL=$(vault kv get -field=url secret/my-blog/database)
export NEXTAUTH_SECRET=$(vault kv get -field=secret secret/my-blog/auth)

# Kubernetes 集成
kubectl create secret generic my-blog-secrets \
 --from-literal=database-url="$DATABASE_URL" \
 --from-literal=nextauth-secret="$NEXTAUTH_SECRET"

21.10 部署检查清单

## 生产部署检查清单

### Docker 镜像
- [ ] 使用 multi-stage build 优化镜像大小
- [ ] 镜像大小 < 300MB
- [ ] 使用 Alpine 或 Distroless 基础镜像
- [ ] 非 root 用户运行
- [ ] 配置了 HEALTHCHECK

### 安全
- [ ] 敏感信息使用 Secrets（不写入代码）
- [ ] 环境变量未泄露到 git
- [ ] HTTPS 已启用
- [ ] Nginx 隐藏了 server 头
- [ ] 依赖已扫描（npm audit、Trivy）

### 性能
- [ ] Standalone output 已启用
- [ ] Gzip / Brotli 压缩已开启
- [ ] 静态资源配置了长期缓存
- [ ] 数据库连接池已配置
- [ ] CDN 已配置（Cloudflare / CloudFront）

### 监控
- [ ] /api/health 端点可访问
- [ ] 日志已收集（Loki / CloudWatch）
- [ ] 错误监控已集成（Sentry）
- [ ] Uptime 监控已配置
- [ ] 告警已设置

### 备份
- [ ] 数据库自动备份（每日）
- [ ] 备份已测试恢复
- [ ] 上传文件有备份（S3 / R2）

### 扩展性
- [ ] 支持水平扩展（无状态）
- [ ] Session 存储在 Redis（而非内存）
- [ ] 文件上传使用外部存储
- [ ] 配置了 auto-scaling（如适用）

### 文档
- [ ] README 包含部署说明
- [ ] 环境变量已文档化
- [ ] Runbook（故障处理手册）已准备
- [ ] 团队成员知晓部署流程

本章小结

Key Takeaways

Standalone Output 是 Docker 部署的前提：镜像更小、启动更快
多阶段构建是 Docker 优化的核心：构建阶段 + 运行阶段分离
GitHub Actions 是 CI/CD 的标准方案：自动化测试、构建、部署
部署方案选择取决于业务需求：Vercel 适合快速、Docker 适合合规、K8s 适合大规模
蓝绿部署和金丝雀发布降低发布风险：渐进式发布、快速回滚
环境变量管理是安全的底线：使用 Secrets、Vault，永不写入代码

下一步

下一章（也是本系列最后一章）我们将深入 多租户 SaaS 架构实战——构建一个完整的多租户博客系统，涵盖租户隔离、计费、权限管理与自定义域名。

第 22 章：多租户 SaaS 架构实战

Wed, 11 Jun 2025 00:00:00 +0000

本章目标：以"多租户博客 SaaS 平台"为实战项目，系统掌握 Next.js 中构建 SaaS 应用的核心技术——租户识别与隔离、数据权限控制、Stripe 订阅计费、自定义域名绑定、团队成员管理，最终交付一个生产可用的多租户系统。

第 10 章：数据库集成（Prisma + PostgreSQL）