Next.js 最佳实践
Next.js App Router 开发原则。
1. 服务端组件与客户端组件
决策树
Does it need...?
│
├── useState, useEffect, event handlers
│ └── Client Component ('use client')
│
├── Direct data fetching, no interactivity
│ └── Server Component (default)
│
└── Both?
└── Split: Server parent + Client child
默认情况
| 类型 | 用途 |
|---|
| 服务端 | 获取数据、布局、静态内容 |
| 客户端 | 表单、按钮、交互式 UI |
2. 数据获取模式
获取策略
| 模式 | 用途 |
|---|
| 默认 | 取决于版本和配置；当前 fetch 默认不缓存 |
| 显式缓存 | 数据可共享时使用 fetch(url, { cache: "force-cache" }) |
| 重新验证 | ISR（按时间刷新） |
| 不存储 | 动态内容（每次请求都获取） |
数据流
| 来源 | 模式 |
|---|
| 数据库 | 在服务端组件中获取 |
| API | 使用缓存进行 fetch |
| 用户输入 | 客户端状态 + 服务端操作 |
3. 路由原则
文件约定
| 文件 | 用途 |
|---|
page.tsx | 路由 UI |
layout.tsx | 共享布局 |
loading.tsx | 加载状态 |
error.tsx | 错误边界 |
not-found.tsx | 404 页面 |
路由组织
| 模式 | 用途 |
|---|
路由组 (name) | 不改变 URL 的情况下组织路由 |
并行路由 @slot | 同一层级的多个页面 |
拦截路由 (.) | 模态覆盖层 |
4. API 路由
路由处理器
| 方法 | 用途 |
|---|
| GET | 读取数据 |
| POST | 创建数据 |
| PUT/PATCH | 更新数据 |
| DELETE | 删除数据 |
最佳实践
- 使用 Zod 验证输入
- 返回适当的状态码
- 妥善处理错误
- 根据依赖项和部署支持情况选择 Node.js 或 Edge 运行时；不要假设 Edge 上可使用 Node API
5. 性能原则
图像优化
- 使用 next/image 组件
- 为首屏内容设置优先级
- 提供模糊占位图
- 使用响应式尺寸
包优化
- 对大型组件使用动态导入
- 基于路由的代码拆分（自动完成）
- 使用 bundle analyzer 进行分析
6. 元数据
静态与动态
| 类型 | 用途 |
|---|
| 静态导出 | 固定元数据 |
| generateMetadata | 按路由动态生成 |
必要标签
- title（50-60 个字符）
- description（150-160 个字符）
- Open Graph 图片
- 规范 URL
7. 缓存策略
缓存层
| 层 | 控制方式 |
|---|
| 请求 | fetch 选项 |
| 数据 | revalidate/tags |
| 完整路由 | 路由配置 |
重新验证
| 方法 | 用途 |
|---|
| 按时间 | revalidate: 60 |
| 按需 | revalidatePath/Tag |
| 不缓存 | no-store |
8. 服务端操作
使用场景
最佳实践
- 标记为 'use server'
- 在服务端对每个操作/处理器进行身份验证和授权；导出的操作是可调用的端点
- 验证所有输入
- 返回类型化响应
- 处理错误
9. 反模式
| ❌ 不要 | ✅ 应该 |
|---|
| 到处使用 'use client' | 默认使用服务端组件 |
| 在客户端组件中获取数据 | 在服务端获取数据 |
| 跳过加载状态 | 使用 loading.tsx |
| 忽略错误边界 | 使用 error.tsx |
| 生成大型客户端包 | 使用动态导入 |
10. 项目结构
app/
├── (marketing)/ # Route group
│ └── page.tsx
├── (dashboard)/
│ ├── layout.tsx # Dashboard layout
│ └── page.tsx
├── api/
│ └── [resource]/
│ └── route.ts
└── components/
└── ui/
请记住： 服务端组件有其默认使用的理由。从服务端组件开始，仅在需要时添加客户端组件。
适用场景
当需要执行概览中描述的工作流或操作时，可使用此技能。
版本范围
在应用缓存建议之前，请检查已安装的 Next.js 版本以及是否启用了 Cache Components。官方缓存指南 对这些模型作了区分。请明确测试数据新鲜度和失效行为；切勿将用户专属机密或依赖授权的响应放入共享缓存。
限制
- 仅当任务明确符合上述范围时，才使用此技能。
- 不要将输出视为特定环境验证、测试或专家评审的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。
