Next.js 16的实践案例和坑点总结
一、基于 Next.js 16 的关键变化（必须知道）
这是你在网上很难看到的“升级后必须掌握的关键点”。
1. Server Components 为默认，Client Components 仅用于交互
Next 16 更强调 SSG/SSR 和 RSC，推荐你：
页面结构统一使用 Server Component
只有交互用 “use client”
带来的优势：
更小的 bundle
更快的首屏
直接访问数据库/后端（无 API）
2. 全新Cache Components（Next 16 最大变化）
Next 16 引入一个新模式：
export default async function Page() { const data = await getData(); // 自动缓存 return <div>{data}</div>; } 特点：
fetch、读数据库、计算结果自动缓存
缓存可按组件级别复用
支持手动 revalidate
你也可以强制禁用缓存：
export const dynamic = "force-dynamic";
或页面级别缓存：
export const revalidate = 60; // 60秒
3. 中间件新方案：proxy.ts
Next 16 引入 Proxy Routes：
app/proxy.ts
它的作用是：
替代 middleware 部分用途
更强能力（可读写 cookies）
能直接拦截所有请求
使用示例：
export default function proxy(request) { const token = request.cookies.get("token"); if (!token) { return Response.redirect("/login"); } } 比 middleware 更灵活。
4. 默认使用Turbopack（更快）
生产环境已经支持：
快速增量编译
更快冷启动
更小打包体积
但现阶段仍有一些兼容性问题（后面会讲坑点）。
5. 全面支持 React 19（useTransition/useForm 等）
Next 16 默认支持：
useFormStatususeActionStateserver actions 更稳定
二、Next.js 16 的项目实战最佳实践
这些是做实际项目最关键的。
1. 目录结构最佳实践
app/ (public)/layout.tsx # 公共布局 dashboard/ page.tsx loading.tsx error.tsx api/ user/route.ts # Route Handlers API lib/ db.ts # 数据库 services/ components/ ui/ # 客户端组件库 server/ # 服务器组件
建议：
| 内容 | 写在哪里 |
|---|---|
| 页面结构 | Server Components |
| 表单、按钮、交互 | Client Components |
| 业务逻辑（读库/计算） | lib/services |
| API 处理 | route.ts |
| 鉴权、重定向 | proxy.ts |
2. 数据获取的最佳实践（强烈推荐）
能在 Server 取数据，一律放 Server。
最推荐的方式：
export default async function Page() { const user = await getUser(); return <UserView user={user} />; } 避免写成下面这种：
（不然就是 CSR）
"use client"; useEffect(() => { fetch("/api/user").then(...) }, []); 3. Server Action 使用策略
处理表单提交最推荐：
"use server" export async function createUser(formData) { const name = formData.get("name"); await db.user.create({ data: { name } }); } 客户端：
<form action={createUser}> <input name="name" /> </form> 优点：
自带 CSRF 防护
自动 SSR 返回结果
网络开销更小
三、Next.js 16 实战最常见35 个坑点
1.use client忘记写 → 事件不触发（最常见）
"use client";
必须放在第一行。
2. Server Component 使用 window / useEffect 直接报错
Server Component 不能：
useState
useEffect
window、document
localStorage
3. fetch 在 Next.js 中默认“缓存”，开发环境和生产环境不一致
很多人踩这里👇
开发环境：
不缓存
生产环境：
默认缓存（SSG）
解决：
fetch(url, { cache: "no-store" }) 4. fetch 自动请求合并（Request Deduping）
相同 fetch 会合并成一次：
const a = fetch("/api/user"); const b = fetch("/api/user"); 🚨 结果后台只收到 1 次请求。
如果你需要多次真实请求：
cache: "no-store"
5. layout.tsx 会持久化渲染，状态不会变化
这导致：
登录后 layout 内部 UI 不刷新
权限侧边栏不更新
解决：
把需要交互的部分移到 Client Component + Context。
6. metadata 不能写在 Client 文件中
必须写在 server component：
export const metadata = { title: "User", }; 7. redirect() / notFound() 不能放在 Client Component 中
SSR 专用。
8. Route Handler 中读取 body 只能读一次
这会报错：
const body1 = await req.json(); const body2 = await req.json(); // ❌
9. 静态资源路径错误：不能写 public
/public/logo.png ❌ /logo.png ✔
10. middleware 和 proxy.ts 配置冲突
proxy 优先级高
middleware 无法覆盖 proxy 的行为。
11. 使用 next/image 导致生产环境 403
你必须配置：
remotePatterns
12. Turbopack 打包时某些库不支持 CommonJS
比如一些老库，用 webpack 才能正常构建。
解决：关闭 turbopack
NEXT_USE_TURBOPACK=0
13. 环境变量必须以 NEXT_PUBLIC_ 才能给客户端用
否则 undefined。
14. “hydration mismatch” 是 Next.js 最常见报错
原因：
Server 渲染的内容 与 Client 不一致
useEffect 中修改初始渲染内容
非受控 → 受控组件切换
15. 动态导入组件，SSR 必须手动关闭
const Editor = dynamic(() => import('./Editor'), { ssr: false }); 16. 在 GitHub / Vercel 构建时 Prisma 报错
因为 schema 未生成：
prisma generate
必须加到构建脚本。
17. Next.js 在边缘运行时不支持 Node API
例如：
fs
path
events
child_process
18. next/link 的 children 不能是空标签
必须：
<Link href="/"><span>Home</span></Link>
19. API route 和 Route Handler 混用会导致路由冲突
推荐只使用：
app/api/**/route.ts
20. 组件变成 Client Component 会让整个子树变成 CSR
这是性能杀手。
尽量拆分：
树顶保持 server
交互组件小颗粒 client
更多坑点（快速列表）
每次刷新 global CSS 会闪屏
Middleware / proxy.ts 不支持 request body
当 Layout 中 useSearchParams 会多次渲染
动态路由不带 trailing slash 会冲突
pages/ 与 app/ 路由同名 → 冲突
使用 form 表单 + JS 禁止默认行为 → 无法 SSR
Route Handler 返回流式响应复杂
静态文件增删不会触发热更新
错误边界 error.tsx 不能用 useEffect 捕获
React Server Components 不支持一些旧 UI 库
next build 不能直接使用 require
bundler 无法处理某些 old-style ESM
preload + next/script 干扰生产环境性能
Bun/PNPM 与 Turbopack 兼容性偶发问题
“Concurrent features” 在 Node 16 以上才稳定
总结
到此这篇关于Next.js 16的实践案例和坑点总结的文章就介绍到这了,更多相关Next.js16实践和坑点内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
最近在使用JS动画做一些练习的时候我发现在动画执行时间内快速移开鼠标时会出现动画因鼠标移动过快从而导致代码冲突让画面抖动的bug,这篇文章主要给大家介绍了关于JavaScript实现动画时动画抖动的原因与解决方法,需要的朋友可以参考下2022-06-06
这篇文章主要介绍了微信头像地址失效踩坑记附带解决方案，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2019-09-09
对于数字键名或者非正常变量字符（比如有空格），必须使用 aa[x]的方式2013-11-11
这篇文章主要为大家详细介绍了js图片查看器的制作方法，可以实现图片的滑动等效果,具有一定的参考价值，感兴趣的小伙伴们可以参考一下2016-11-11
这篇文章主要介绍了fetch跨域问题的使用详解,fetch 的核心主要包括：Request , Response , Header , Body，利用了请求的异步特性 --- 它是基于 promise 的，本文通过实例代码给大家介绍的非常详细，需要的朋友可以参考下2022-09-09
这篇文章主要介绍了JavaScript Module模式的相关资料，文中讲解非常细致，代码帮助大家更好的理解和学习，感兴趣的朋友可以了解下2020-07-07
本节代码主要使用了Document对象关于窗口的一些属性，附实现代码及源程序解决，有需求的朋友可以参考下2013-07-07
这篇文章主要给大家介绍了关于利用Three.js开发实现3D地图的实践过程，文中通过示例代码介绍的非常详细，对大家学习或者使用three.js具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧。2017-11-11
这篇文章主要为大家详细介绍了js面向对象之实现淘宝放大镜，文中示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2020-01-01
javascript操作Cookie（设置、读取、删除）方法详解
这篇文章主要详细向大家介绍了javascript操作Cookie的方法，包括设置、读取、删除操作，十分的细致全面，附上示例，是篇非常不错的文章，这里推荐给大家。2015-03-03
最新评论