Markdown 交叉引用转 Word 后失效？图片、表格、公式与章节编号排查指南

一份文档中的标题、图片、表格和公式可能都已经正常排版，但内部交叉引用仍然会出错。Word 中可能显示原始标签、错误编号，或者一段不会随着内容移动而更新的普通文字，而不是“见图 3”或“参见第 2.4 节”。

交叉引用依赖稳定的引用目标。Markdown 源文件需要为标题、图片、表格、公式或附录设置唯一标识，正文引用必须准确指向该标识；目标还需要具备 Word 可以识别的题注或编号结构。

一条交叉引用需要哪些部分

可靠的交叉引用包含两个部分：

• 引用目标：被引用的标题、图片、表格、公式或附录。
• 正文引用：引导读者查看目标对象的句子。

一个简化的源码结构可以写成：

![系统架构](images/architecture.png){#fig-architecture}

各组件之间的关系见图 @fig-architecture。

不同 Markdown 实现的具体语法可能不同，但核心原则一致：目标标识和引用标识必须完全匹配。

问题一：目标没有稳定标识

“系统架构”这样的题注对读者可见，但不一定是唯一、可供程序识别的目标。文档存在多个类似题注时，转换程序无法可靠判断引用应该指向哪一个对象。

![系统架构](images/architecture.png)

系统架构见上图。

“上图”在当前内容中可以理解，但插入新段落或图片后就可能失效。稳定标识更可靠：

![系统架构](images/architecture.png){#fig-system-architecture}

系统架构见图 @fig-system-architecture。

问题二：引用标签与目标标签不匹配

应把标签当作精确标识符。不要增加空格、修改大小写，或者重命名目标后忘记同步全部引用。

问题三：两个目标重复使用同一标签

重复标识会产生歧义。如果两张图片都使用 fig-overview，转换程序可能指向第一张、最后一张，或者直接无法解析。

![架构概览](images/architecture.png){#fig-overview}

……

![部署概览](images/deployment.png){#fig-overview}

应使用能够区分目标的标签：

{#fig-architecture-overview}
{#fig-deployment-overview}

统一前缀也便于搜索大型源文件：

• fig-：图片
• tbl-：表格
• eq-：公式
• sec-：章节
• app-：附录

问题四：题注与对象分离

图片或表格题注应在结构上紧邻它所描述的对象。中间插入多个无关段落、手工分页符或其他对象，可能让两者关系变得不清晰。

源码结构应尽量紧凑：

![请求处理流程](images/request-flow.png){#fig-request-flow}

图：请求处理流程

如果文档需要自动编号，不要在题注中手工输入“图 4”。插入、删除或调整图片顺序后，手工数字很容易失效。

问题五：手工编号不会自动更新

“见表 6”只是普通文字，除非它与引用目标或 Word 域建立了关联。表格移动后，这句话仍然会显示“表 6”。

最终显示形式取决于转换规则和模板，但源文件应该指向目标，而不是提前猜测最终编号。

章节引用需要稳定标题结构

只有标题层级保持一致，章节引用才更可靠。标题从 H2 直接跳到 H4，或者用粗体正文代替标题，都可能破坏预期编号层级。

## 部署流程 {#sec-deployment}

### 部署前检查

### 发布流程

完整流程见第 @sec-deployment 节。

启用标题编号后，应检查最终章节数字。未启用编号时，则需要判断引用是否应该显示章节标题，而不是数字。

公式引用需要单独检查

公式本身可以正常生成，但标签仍可能失效。标识应放在转换流程支持的位置，不要在公式图片或源码中手工输入编号。

$$
d = \frac{p \times D}{w}
$$ {#eq-clearance}

净空估算由公式 @eq-clearance 定义。

转换后检查：

• 公式是否保持可编辑。
• 编号是否显示并位于正确位置。
• 引用是否指向公式，而不是周围段落。
• 插入另一条公式后，两个编号是否同步变化。

表格和题注中的交叉引用

狭窄表格单元格或题注中的引用即使能够工作，也可能产生较差排版。过长的标题、章节名称或多条引用会让单元格行高异常增加。

为了提高可读性：

• 只有文档规范允许时才使用“图”“表”的缩写。
• 多条引用可以移到表格下方说明。
• 不要把重要导航信息只放在图片题注中。
• 条件允许时，把交叉引用放在普通正文中。

可靠的排查流程

1. 找到第一个未解析引用。复制准确标签。
2. 搜索目标。确认存在一条匹配标识。
3. 检查重复标签。在完整文档中搜索同一目标标识。
4. 检查目标结构。确认题注、标题、表格、图片或公式能够被识别。
5. 删除手工编号。让目标和 Word 域控制可见数字。
6. 建立最小测试。只保留一个目标和一条引用。
7. 转换并更新域。打开 DOCX，并在需要时刷新 Word 域。
8. 把正确结构放回完整文档。再分别检查所有引用类型。

检查最终 DOCX

常见现象与处理方式

常见问题

最终检查清单