Next.js hydration error 怎么排查：新手检查清单

这份清单用于排查 Next.js hydration error 前的自查。完整说明可以看 Next.js hydration error 怎么排查。清单目标是把“页面报错了”变成可复现、可验证、可交付的诊断任务。

本文保持草稿状态，不建议你直接接管客户生产权限、真实数据库、支付配置或私密账号。涉及客户仓库、部署后台、访问授权和生产日志的内容，都先进入明日待办。

适合谁

适合正在练习 Next.js、React、Vercel 部署或前端小修的新手。你可以用清单整理报错材料，再决定是否适合作为低风险练习或诊断小单。

也适合接到客户报错截图时使用。你的第一步不是立刻改代码，而是确认错误是否能复现、范围是否明确、验证方式是否清楚。

不适合谁

不适合没有报错原文、没有页面路径、没有运行方式就承诺修复的人。材料不足时，应先定义为诊断，不是确定修复。

也不适合新手独立处理生产支付页、真实用户数据、复杂权限、灰度发布或大规模流量页面。这些需要更严格的复核和测试流程。

具体步骤

1. 收集报错原文和截图。
2. 确认复现路径和运行环境。
3. 找最近改动的组件和依赖。
4. 按服务端/客户端差异逐项排查。
5. 缩小到一个组件或一个渲染分支。
6. 修复后运行构建和页面复测。
7. 保存修改说明、验证结果和剩余风险。

1. 报错材料检查

• [ ] 已复制完整控制台报错。
• [ ] 已保存页面路径和截图。
• [ ] 已记录是开发环境、本地构建、预览环境还是线上环境。
• [ ] 已记录浏览器、设备和是否刷新后必现。
• [ ] 已记录最近改动的文件或组件。

没有这些材料时，不要急着改代码。先把客户问题变成可诊断材料。

2. 复现检查

• [ ] 本地能否复现。
• [ ] 生产构建后能否复现。
• [ ] 刷新页面是否必现。
• [ ] 切换移动端宽度是否出现。
• [ ] 清空本地存储或换浏览器后是否变化。

复现结果要写下来。不能复现时，交付范围应该是“诊断和建议”，不是“已修复”。

3. 常见原因检查

• [ ] 首屏是否使用 Date.now()、new Date() 或随机数。
• [ ] 首屏是否直接读取 window、document、localStorage 或浏览器尺寸。
• [ ] 主题、语言、用户设置是否影响首屏内容。
• [ ] 是否有依赖 DOM 的图表、地图、编辑器或动画组件。
• [ ] HTML 标签嵌套是否可能不合法。
• [ ] 服务端数据和客户端数据是否可能不同步。

这些项目不代表一定有问题，但它们是新手最值得优先看的方向。

4. 修复验证检查

• [ ] 修改范围只集中在可疑组件或渲染分支。
• [ ] 已运行 npm run lint 或项目已有 lint 命令。
• [ ] 已运行 npm run build 或项目已有构建命令。
• [ ] 已在目标页面刷新复测。
• [ ] 已检查桌面端和移动端。
• [ ] 已保存修复前后截图或输出记录。

构建通过不等于业务验收完成。它只能证明代码可以构建，还要看目标页面是否真的不再报错。

风险提醒

不要为了消除报错就全局关闭服务端渲染。局部客户端渲染可以是方案之一，但需要说明代价。

不要在客户生产环境里边猜边改。先用测试分支、预览链接或本地复现验证。

不要把 AI 输出直接当修复结论。AI 可以帮你列方向，但最终要靠复现、代码修改和构建结果证明。

5. 明日人工复核清单

• [ ] 核对当前 Next.js 和 React 官方文档中关于 hydration 的说明。
• [ ] 准备一个脱敏复现案例，包含报错原文、代码片段和截图。
• [ ] 确认是否需要客户仓库访问、测试分支或 Vercel 预览链接。
• [ ] 确认不接触生产数据库、支付配置、真实用户数据或私密账号。
• [ ] 写一份客户确认问题：页面路径、复现步骤、最近改动和验收标准。
• [ ] 人工复核代码片段、修复说明和服务范围。

记录模板

报错原文：
页面路径：
运行环境：
复现步骤：
最近改动：
怀疑原因：
修改范围：
验证命令：
验证结果：
剩余风险：

相关内容

• Next.js hydration error 怎么排查
• AI 编程工具使用前要检查哪些风险
• 用 Claude Code 排查客户报错时怎么做才稳
• 模板下载

免责声明

本文是学习型草稿，不构成职业保证、项目承诺或生产环境操作建议。Next.js 和 React 的具体错误提示、推荐写法和框架行为可能变化。发布前需要人工核对官方文档、真实复现案例和安全边界。