使用Next.js开发时难免遇到各种报错，本文梳理了8个高频问题及解决思路，涵盖SSR环境下的典型陷阱。
1. ReferenceError: document is not defined — 将浏览器API调用放在useEffect内，或检查是否仅在客户端运行。
2. 环境变量返回undefined — 检查.env.local文件、重启开发服务器、需要NEXT_PUBLIC_前缀的变量加前缀、检查拼写。
3. 水合错误 — 避免在服务端和客户端渲染不一致的值，如Date.now()、Math.random()，使用useState和useEffect控制。
4. MongoDB连接失败 — 检查连接字符串、用户名密码、IP白名单、DNS解析和环境变量。
5. Module not found — 检查文件存在性、导入路径、包是否安装、重启服务器。
6. Hook调用无效 — 确保hooks不在条件、循环或嵌套函数中调用，始终在组件顶层。
7. 在客户端组件中导入服务端组件 — 使用'use client'标记需要客户端能力（state、事件等）的组件。
8. 图片无法加载 — 在next.config.js的remotePatterns中添加图片域名。
这些错误背后往往指向服务端渲染、水合等核心概念，理解原理比记忆API更有助于长期调试。
#开发者 #工具 #Nextjs #React #SSR #调试 #前端
📢 频道：@DevToolboxHub