Next.js爬坑总结
作为一个写惯了纯前端 SPA 的开发，第一次用 Next.js App Router 做项目，本以为是开箱即用的全栈神器，结果被服务端组件、渲染机制、路由规则按在地上摩擦。
没有枯燥的理论，全是我踩坑踩出来的血泪史，专治各种渲染报错、路由404、数据不更新，看完直接少走一周弯路。
一、组件渲染：分不清客户端/服务端，BUG直接找上门
- 写个 useState 直接报错？默认全是服务端组件！
刚上手最崩溃的瞬间，随手写个计数器，编辑器直接爆红。后来才知道，App Router 下所有组件默认是服务端组件，压根不能用任何客户端 Hooks。
// 致命错误：服务端组件用客户端API
export default function Home() {
const [count, setCount] = useState(0);
return {count}}解决办法：带交互、状态的组件，顶部第一行加 'use client'，没有任何捷径。
- 敢在服务端用 window？直接编译失败
服务端渲染没有浏览器环境，document、localStorage 这些常用API一用就报错。别硬扛，要么改成客户端组件，要么用 useEffect 包裹执行。
二、路由系统：文件名决定一切，错一个字符就404
- 路由跳转 hooks 都能写错？
别再用 Pages Router 的习惯写代码了！App Router 已经把 useRouter 迁移到了 next/navigation，导包错了，路由直接废了。
'use client'
import { useRouter } from 'next/navigation'
// 这才是正确的打开方式
const router = useRouter();- 动态路由、嵌套路由命名规则太苛刻
动态路由必须用 [id] 命名文件夹，页面组件只能叫 page.tsx，全局布局只能是 layout.tsx。少个字母、拼错单词，页面直接404找不到。
三、数据请求：默认缓存是大坑，数据永远不更新
fetch 自动缓存？新项目上线才发现数据是旧的
Next.js 为了性能默认缓存所有请求，导致实时数据完全不刷新，这个坑我上线前才发现，差点酿成大祸。
// 关闭强制缓存，保证数据实时性
const res = await fetch("https://api.xxx.com", {
cache: "no-store"
});记住：后台管理、实时数据类页面，必须关闭默认缓存！
四、图片组件：next/image 看着好用，全是限制
想用优化后的图片组件？先接受它的一堆规则：必须宽高、远程图片要配置白名单、本地图片不能直接写路径。
新手最常犯的错：外网图片不配置 next.config.js，直接跨域报错，折腾半天才找到原因。
五、环境变量：客户端访问不到？前缀加对了吗
服务端变量直接用，客户端变量必须以 NEXTPUBLIC 开头，这是铁律。我因为少加了这个前缀，接口请求报错了一上午。
六、第三方UI库：一引入就报错，全是渲染兼容问题
AntD、Element Plus 这些常用UI库，直接在服务端组件使用必报错。原因很简单：UI库依赖浏览器API，必须套一层客户端组件才能正常使用。
七、打包部署：静态导出和服务端组件二选一
想开启静态导出？那所有服务端渲染的功能全部作废。很多人打包后页面白屏、样式丢失，都是因为同时开启了不兼容的配置。
八、最后说句真心话
Next.js 很强，但它的学习成本全在规则里。
它不像纯前端那样随心所欲，服务端与客户端的边界、路由的严格规范、缓存的默认机制，每一处都需要我们适应。
把这些坑记牢，你会发现 App Router 远比想象中好用。毕竟，踩完所有坑，剩下的就是真香时刻了。
评论