踩坑记录
每一条踩坑记录都是用时间买的经验。记录的目的不是证明「我踩过」，而是下次遇到同类问题时十分钟内脱坑，并把经验固化成可复用的写法。
记录方法：五段式
按「现象 → 排查过程 → 根因 → 解决方案 → 预防」五段记录，标题写清问题关键词，方便日后搜索。直接复制：
markdown
---
title: 踩坑：标题写问题关键词（技术栈 + 报错/现象）
description: 一句话现象
tags:
- 踩坑记录
- <技术栈标签，如 前端 / 构建>
---
# 踩坑：xxx
## 现象
- 复现步骤（版本、环境、触发操作）
- 实际表现（报错原文 / 截图描述 / 异常行为）
## 排查过程
- 试过什么，排除了什么（写「排除项」能避免别人重复踩）
- 定位到关键线索的瞬间
## 根因
- 一句话本质原因（概念理解错 / API 用错 / 环境差异 / 工具默认行为）
- 为什么会产生这个现象，把因果讲通
## 解决方案
- 最小改动 / 正确写法（贴关键代码）
- 验证结果（跑通、报错消失）
## 预防
- 怎么写以后不会再踩（检查清单项 / lint 规则 / 文档备注）
- 关联的正式笔记链接怎么记录才有效
| 阶段 | 要求 | 反例 |
|---|---|---|
| 现象 | 含版本环境与报错原文，可复现 | 「报错了」 |
| 排查过程 | 写排除过的假设，缩短别人排查路径 | 直接跳结论 |
| 根因 | 讲清因果，不是贴解决方案的「因为所以」 | 「就是这样，改了就对了」 |
| 解决方案 | 最小可复制代码 + 验证结果 | 只给思路不给代码 |
| 预防 | 落到可执行的动作（检查项 / 规则 / 写法） | 「下次注意」 |
站内分类索引
各领域正式文档中已内置「踩坑 / 常见误区」小节，这里统一收口：日常排错先到对应模块查找，找不到的坑再按五段式新增到本页。
| 分类 | 站内直达 | 覆盖的典型坑 |
|---|---|---|
| 前端 | React 踩坑 · Angular 踩坑 · 样式方案 · 微前端 · 前端安全 | Hooks 依赖、signal.mutate() 移除、CSS 变量层叠、沙箱隔离、密钥泄漏 |
| 构建与测试 | 构建工具 · 测试 · 性能优化 · 浏览器原理 | Vite HMR 边界、快照滥用、长任务、事件循环时序 |
| 后端 | Node.js / NestJS · Spring Boot · Go · 数据库 · 缓存 · 消息队列 | 背压、@Transactional 自调用、context 取消、索引失效、缓存击穿、幂等键 |
| 语言 | JavaScript · Rust · 语言对比 | 闭包、所有权、null 处理差异 |
| AI | Prompt · RAG 与 Agent · 模型微调 · AI 工程化 | 提示注入、评测集污染、显存估算、量化格式 |
| 过程习惯 | 本站「写作规范」与 项目复盘 | 见下方「高频坑位 TOP」 |
本站实例（真实收录）
写作与构建本站时踩过的坑，均已在对应文档修复并沉淀为规范：
| 现象 | 根因 | 解决 | 关联页 |
|---|---|---|---|
Angular 页面整页白屏，控制台 Cannot read properties of undefined (reading 'name') | VitePress 将 Markdown 编译为 Vue 模板，正文展示 Vue 插值语法（双花括号包表达式）时被当作插值求值 | 用 <code v-pre> 包裹跳过后缀编译，全文件扫描确认无裸露插值 | Angular |
vitepress build 在 client/server bundles 阶段报 Element is missing end tag 终止 | 正文裸写 <head> 被 Vue 编译器当作真实 HTML 标签解析 | 改反引号包裹，全文件扫描确认无其他裸露标签 | 浏览器原理 |
| 构建期报告 dead link 失败 | 相对链接 ./vue/ecosystem/vitest/ 解析到不存在的 vitest/index（该子主题无首页） | 改为指向实际入口页 getting-started | 测试 |
| Rust 示例编译报错 | ? 传播错误后函数返回类型不匹配，漏包 Ok | 补齐 Ok 包裹后通过编译，示例均基于 rustc 实跑验证 | Rust |
以上各条在原始记录中均含「现象 → 根因 → 解决」完整过程；正式收录后浓缩为表格便于速查。
高频坑位 TOP
来自本站多篇文章反复出现的行为层高频坑（与具体技术无关，先自查再查代码）：
- [ ] 教程跟着敲的时间远大于自己写的时间，项目永远「会跑不会造」；
- [ ] 框架/语言浅尝辄止频繁横跳，一套没学透就换下一个；
- [ ] 跳过部署与真实联调，作品只存在于本地；
- [ ] 示例代码没在真实运行时验证就收录进文档（版本、输出、报错都要实测）；
- [ ] 笔记直接复制文档原文，不留自己的话（学完即忘的根源）；
- [ ] 写 Markdown 不检查裸标签 / 裸插值 / 相对链接，导致整站构建失败。
从日志到踩坑记录
日常在学习日志里记下「疑问与卡点」，满足任一条件就升级为独立踩坑条目：
| 信号 | 动作 |
|---|---|
| 排错耗时超过半天 | 必须写，五段式能保住排错路径 |
| 同一坑第二次出现 | 立即写，先查本页再动手 |
| 坑可被某条规范 / lint / 写法根治 | 写完预防后，把预防动作补进对应领域文档 |
写作规范速记
- 命名
pitfall-<技术栈>-<问题关键词>.md或直接在分类小节新增小节； - 标题必须含可搜索的问题关键词（报错名 / API / 框架名）；
- 五段式缺一不可，其中「排查过程」与「预防」最容易偷懒，也最值钱；
- 涉及具体技术细节时链接到对应领域的正式笔记，避免本页重复堆代码。
写作规范请参阅过程记录。