99 · 速查表与兜底清单

按报错关键字速查

关键字	大概率原因	跳转
Failed to resolve import	路径 / 别名 / 大小写	02 §2.1
Cannot find module	没装 / TS paths 没配	01 §1.3 / 03 §3.1
Unexpected token '<'	MIME 错 / 路由兜底	02 §2.3 / 06 §6.5
ERESOLVE	peer 冲突	01 §1.1
Maximum update depth	effect 依赖引用变化	04 §4.3
Hooks can only be called	两份 React / 条件调用	04 §4.1
Network Error	后端没起 / 代理错	05 §5.1
Rollup failed to resolve	缺依赖声明	06 §6.1
[hmr] Failed to reload	源码语法错	07
JSX element implicitly any	tsconfig jsx 没配	03 §3.3
Loading chunk N failed	发版后旧 index.html 引用新 chunk	06 §6.7
401	token 失效 / 拦截器没加	05 §5.2
CORS	绕过了代理 / 直连后端	05 §5.3
Yjs was already imported	Yjs 多版本	09 §9.2

按现象分类

白屏

1. 控制台报 Unexpected token '<' → MIME / 路由 → 02 §2.3
2. 控制台报 Loading chunk failed → 老 index.html → 06 §6.7
3. 控制台报 React Error #185 → 状态相关报错 → 04
4. 控制台空白 → sourcemap 没开?用旧浏览器?→ 06 §6.10

不更新 / 渲染异常

1. Zustand 改了 state 组件不更新 → selector 问题 → 04 §4.6.1
2. effect 跑了两次 → StrictMode 故意行为 → 04 §4.8
3. 路由切换 state 没重置 → 加 key → 04 §4.7.3
4. HMR 改 CSS 不生效 → 引入方式 → 07

启动报错

1. npm install 卡 ERESOLVE → 01 §1.1
2. vite 起来后 import 报错 → 02 §2.1
3. tsc -b 报类型错 → 03
4. 端口被占 → 02 §2.7

---

兜底排查清单(逐项打勾)

• Node 版本 node -v ≥ 18(Vite 5 要求)
• React 单实例 cd frontend && npm ls react 只有一份
• Vite 缓存 rm -rf frontend/node_modules/.vite 清掉重启过
• TS 别名 tsconfig.json 的 paths 与 vite.config.ts 的 alias 一致
• 后端在跑 9002 端口活着 curl http://localhost:9002/health
• 代理路径 axios 用 /api 相对路径,不要写完整 URL
• 硬刷新 浏览器 Ctrl+Shift+R 避开 SW / 缓存
• 隐身模式 排除浏览器扩展(React DevTools 旧版会报奇怪错)
• CI 用 npm ci 不是 npm i,严格按 lock 版本
• 大小写 文件名 import 路径大小写一致(Linux 敏感)
• 环境变量 .env.* 用 VITE_ 前缀
• sourcemap dev 默认开,prod 视情况

---

快速命令

# 完全重置前端
cd frontend
rm -rf node_modules/.vite dist node_modules package-lock.json
npm install
npm run dev

# 看依赖重复
npm ls react react-dom yjs

# 类型检查独立跑
npx tsc -b --noEmit

# 体积分析
npm run build && du -sh dist/assets/*.js | sort -h

# 看 Vite 实际处理流程
npx vite --debug

# 查端口占用(Windows)
netstat -ano | findstr 5173
taskkill /F /PID <pid>

---

不在文档里的报错怎么办

1. 完整搜索报错关键句 — 把变量名、路径替换成 xxx,搜库的、谷歌的、官方 issue 都试
2. 看官方 GitHub issues — 比 Stack Overflow 时效更新
3. 二分法定位 — 删除最近改动看是否复现
4. 最小复现 repo — 提 issue 前先做出来,过程中往往自己就发现根因
5. 回到 00-通用定位思路.md — 工具准备齐全了吗?
6. 补充到本文档 — 解决后追加到对应章节,下次自己/同事不踩重复坑