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实践和坑点内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
我们在进行图片保存的时候经常会发现图片跨域了,下面下面这篇文章主要给大家介绍了关于html2canvas图片跨域问题的相关资料,需要的朋友可以参考下2023-03-03
moment.js是一个广泛使用的JavaScript日期处理库,便于开发者进行日期的解析、验证、操作和格式化,通过引用并设置区域,可以轻松实现本地化日期和时间的处理,文中通过代码介绍的非常详细,需要的朋友可以参考下2024-09-09
使用webpack/gulp构建TypeScript项目的方法示例
这篇文章主要介绍了使用webpack/gulp构建TypeScript项目的方法示例，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2019-12-12
定单管理上 JS表格排序...2006-10-10
本篇文章主要介绍了关于webpack代码拆分的解析，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧2017-07-07
利用CSS、JavaScript及Ajax实现图片预加载的方法
预加载图片是提高用户体验的一个很好方法，实现图片预加载可以使用css、JavaScript、Ajax三种方法。下面逐一给大家介绍利用CSS、JavaScript及Ajax实现图片预加载的方法，需要的朋友参考下吧2016-11-11
async 函数就是隧道尽头的亮光，很多人认为它是异步操作的终极解决方案。接下来通过本文给大家分享js 中async 函数的含义和用法，感兴趣的朋友跟随脚本之家小编一起看看吧2018-05-05
这篇文章主要介绍了js实现的四级左侧网站分类菜单,实例分析了javascript操作页面元素实现tab切换的相关技巧,需要的朋友可以参考下2015-05-05
这篇文章主要介绍了如何利用ES6进行Promise封装总结，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2019-02-02
这篇文章主要是对Javascript对象属性方法进行了详细的汇总介绍。需要的朋友可以过来参考下，希望对大家有所帮助2013-11-11
最新评论