首页 > 网络编程 > JavaScript > javascript技巧 > Next.js16实践和坑点

Next.js 16的实践案例和坑点总结

2026-01-24 10:25:26 作者：懒人村杂货铺

Next.js16的到来,总体来说对Next.js开发者来说是好事,并且让我看到了未来在技术选择中,是否对AI友好将会成为关键点,这篇文章主要介绍了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 默认支持：

useFormStatus
useActionState
server 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

总结

到此这篇关于Next.js 16的实践案例和坑点总结的文章就介绍到这了,更多相关Next.js16实践和坑点内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！