6.4 常见渲染问题排错手册
6.4 常见渲染问题排错手册
按症状索引的渲染故障排查清单：列表断裂、标题变文字、表格成竖线、图不显示……每一项给症状、病因、药方。全书散落的排错知识在这里收拢成一张可以贴在工位的手册。
使用方法
先按 6.3 节的心法分诊：块级症状（结构乱了）查行首与缩进；行内症状（记号没生效）查定界符；图和扩展类查解析器配置。然后对号入座。
块级故障区
症状：列表编号从 1 重新开始 / 列表中段断裂
病因：中间那段的缩进没对齐列表项文字列，或中间插入了未缩进的空行加普通段落。
药方：项内内容统一缩进到与项文字起始列对齐；项内空段保持缩进（列表标记符可省略）。
症状：两行文字被并成一行
病因：单回车不是段落边界（CommonMark 语义）。
药方：段间用空行；段内换行用行尾两空格、反斜杠或换行标签。
症状：# 标题 显示为普通文字
病因：井号后缺空格；或该行上一行是文字且构成了其它块。
药方：井号后加空格；标题前留空行。
症状：分割线下面那行变成了大标题
病因：--- 紧贴上方文字行，被解析为 Setext 式二级标题的下划线。
药方：分割线与上下内容之间各留空行。
症状：表格渲染成一堆竖线文字
病因：目标环境不支持表格（非 GFM）；或表格上下缺空行；或分隔行的减号数量异常。
药方：先确认环境支持；补空行；检查分隔行格式 | --- | --- |。
症状：引用块"吃掉"了后面的正文
病因：后续行也以大于号开头，或懒续行规则把内容并了进去。
药方：区块结束后写一行不以大于号开头的非空内容。
行内故障区
症状：星号包裹的文字没有变斜体
病因：定界符与文字的边界不合法（星号与文字间有空格、或与中文标点的组合踩了方言分歧）。
药方：紧贴文字；尝试换成下划线之外的统一星号写法；还不行就检查是否在 HTML 块内。
症状：链接显示成了带方括号的原文
病因：方括号与圆括号之间有空格；用了全角括号；引用式的定义缺失或标记不一致。
药方：三查——空格、全角、定义配对。
症状：想显示的星号被吞了
病因：星号被解析为强调定界符。
药方：反斜杠转义，或行内代码包裹。
图片与扩展故障区
症状：图片不显示，出现替代文字或链接
病因：少了感叹号；替代文本方括号与圆括号结构破损；图片地址失效或被平台图床规则拦截。
药方：核对结构 ! + [] + ()；线上环境优先用平台图床；相对路径检查部署基准目录。
症状：Mermaid 或 SVG 显示为源码
病因：平台解析器未配置对应渲染能力，或围栏语言标注拼写错误。
药方：确认围栏首行是 mermaid / svg；查平台支持说明；Mermaid 图检查标签内是否混入了括号星号等禁忌符号。
症状：脚注编号悬浮、解释不落地
病因：定义缺失、标记不一致、或定义里用了中文冒号。
药方：锚点与定义逐字比对，冒号用英文半角。
症状：HTML 元素消失
病因：平台安全过滤（script/iframe/style 类被剥离）。
药方：改用允许的标签或平台原生能力；别试图绕过过滤。
⚠️ 通用兜底：二分定位法——把出问题的片段复制到一个新文档，每次删一半，看问题是否复现。再诡异的渲染问题，几次二分后总能锁定的那一两行，就是真正的病灶。
故障分诊地图
工具化排错：两段脚本覆盖六成症状
手册用熟之后，把最高频的排查也交给脚本。头号元凶全角标点与行尾空格，肉眼极难发现，正则却一抓一个准：
# 全库扫描全角标点（中文括号、冒号、逗号混进语法位置的高危字符） grep -rnE "（|）|：|，|；" --include="*.md" docs/ | head -20 # 行尾双空格（换行写法）在团队禁用时也会现形 grep -rnE " +$" --include="*.md" docs/ | head -10
第二段脚本做链接与图片引用的完整性检查——图挂与死链是发布后才发现的故障，构建期就能扫出：
# 图片引用的文件是否真的存在 grep -rhoE "!\[[^]]*\]\(([^)]+)\)" --include="*.md" docs/ \ | sed -E 's/.*\(([^)]+)\).*/\1/' | sort -u \ | while read -r img; do [ -f "docs/$img" ] || echo "缺失: $img" done
两段脚本加起来不到十行，覆盖手册里"行内故障区"的大半和"图件故障区"的预防。它们与 6.1 的 lint 脚本同构，可以合并成团队的一个检查命令，本地提交前跑一遍、CI 里再守一道。排错手册的最高形态不是人人背熟，而是大部分条目被脚本预拦，剩下真正需要人来判断的，才是这本手册要教的手感。
本节要点回顾
- 先分诊后下手：块级查行首缩进、行内查定界符、图件查结构与配置。
- 空行是块级语法的万能急救，八成结构问题补个空行就好。
- 全角标点与多余空格是行内故障的头号元凶。
- 二分定位法是最后兜底，专治一切"玄学"。
排错案例三则：完整推理过程
案例一：某文档在编辑器预览里表格正常，发布到站后变成一串普通文字。推理：预览正常说明源码语法正确，发布端异常锁定解析器配置——该站点未启用 GFM 表格扩展（或表格前后缺空行被并进段落）。处置：查站点配置确认无表格扩展后，把表格改为 HTML 写法。案例二：脚注在页尾显示，但正文里的锚是原样文字。推理：锚与定义的标记不一致（一个全角字符混入），解析器找不到配对定义，锚按普通文字处理；对照发现正文里是 [^1] 而定义是 [^1：]（全角冒号）。处置：统一为半角冒号。案例三：嵌套列表第二层全部变成代码块。推理：缩进过度（八空格以上且无父项上下文时按缩进代码块处理），源于粘贴自带的前导空格。处置：删多余缩进。三则案例的方法论一致：症状分类 → 唯一嫌疑 → 最小修改验证，这个三步推理比背一百个案例更耐用。
排错之外：预防性写法清单
排错是事后，更省力的是事前。给一份预防性写法清单，照做能避开手册里大半条目：块级元素（标题、列表、表格、代码块、引用）前后各留一个空行；行内记号两侧与标点之间留空格；符号一律半角输入并在输入法里关掉"自动转全角"；表格每列结尾的管道不省略；链接与图片的 ]( 之间不插任何字符；从外部粘贴的内容先过一遍"粘贴为纯文本"再重新套格式。六条全部是零成本习惯，坚持两周即成肌肉记忆。手册条目依然有用——它们处理的是别人写的旧文档与防不住的意外，但你自己新写的内容，九成问题在敲键盘那一刻就已经避免了。