Word 文档可能看起来组织得很完美，但仍然会产生混乱的 Markdown。原因通常是结构性的：Word 可以使用字体、间距、浮动对象和自定义样式创建视觉效果，而 Markdown 需要明确的标题、列表、链接和表格。
对 Word 到 Markdown 转换进行故障排除的最快方法是识别第一个不正确的元素，检查它是如何在 Word 中创建的，更正该结构，并在再次转换整个文档之前测试一个小副本。 本指南提供了可重复的诊断，而不是随机格式化技巧的集合。
快速诊断表
| 症状 | 最可能的原因 | 第一个尝试修复 |
|---|---|---|
| 标题变为粗体文本 | 手动字体格式而不是 Word 标题样式 | 应用标题 1、标题 2 或标题 3 |
| 列表丢失嵌套或编号 | 输入项目符号、选项卡或中断列表延续 | 使用 Word 列表控件重建 |
| 表格式错误 | 合并单元格、嵌套表格或单元格内的换行符 | 简化为矩形网格 |
| 图像丢失 | 转换器不导出媒体资产 | 提取图像并添加相关参考 |
| 标注或侧边栏消失 | 内容位于文本框或浮动形状内 | 将重要文本移至普通段落 |
| 代码变成普通散文 | 等宽外观没有可靠的结构映射 | 转换后添加 Markdown 栅栏 |
| 脚注或评论数据消失 | 不受支持的注释、评论或修订 | 接受/拒绝更改并单独保存注释 |
| 链接文本保留，但 URL 丢失 | 文本仅看起来像链接或使用不受支持的内部目标 | 重新创建真正的 Word 超链接 |
| 输出为空 | 文件类型错误、DOCX 损坏或纯图像内容 | 重新保存一个干净的 .docx 并测试一段 |
| 转换速度慢 | 大型嵌入式媒体或有限的浏览器内存 | 压缩图像或分割文档 |
| 字符看起来不对 | 目标编码或字体问题 | 保存并渲染为 UTF-8 |
.doc 文件被拒绝 | 旧版二进制 Word 格式 | 保存一个新的 .docx 首先复制 |
从受控测试开始
在编辑 100 页文档之前，创建一个小型诊断副本，其中包含：
- 一个标题 1 和一个标题 2；
- 带有粗体、斜体和超链接的普通段落；
- 一个编号列表和一个嵌套项目符号列表；
- 一个简单的两列表；
- 失败元素的一个示例。
转换该文件 WordToMD. If the clean examples work, the converter is running correctly and the problem is probably in the original document structure. If the small file also fails, save it again as a fresh .docx，尝试其他现代浏览器，并检查显示的错误或转换注释。
此受控测试将三种不同的故障类别分开：
- 来源问题： Word 以意外的方式对内容进行编码。
- 映射限制： 该元素没有直接的 Markdown 等效项。
- 目的地问题： Markdown 是有效的，但最终平台呈现不同的方言。
问题 1：标题转换为粗体段落
为什么会发生
将一条线设置为 20 点、粗体和蓝色，并不会使它成为文档结构中的标题。它可能仍然使用Word的Normal样式。转换器看到的是样式段落，而不是标题 2。
如何修复它
- 在 Word 中选择完整的标题段落。
- 打开“样式”面板。
- 根据层次结构应用标题 1、标题 2 或标题 3。
- 使用 Word 的导航窗格验证它是否出现在大纲中。
- 再次转换测试部分。
不要根据视觉大小选择标题级别。使用标题 1 作为文档标题，使用标题 2 作为主要章节，使用标题 3 作为小节。如有必要，可自定义这些样式在 Word 中的外观，但保留其语义角色。
参见 Markdown 标题指南 完整的层次结构示例。
问题 2：列表丢失嵌套、重新启动或变成纯文本
为什么会发生
以键入的破折号开头的行不一定是Word列表项。同样，按 Tab 或插入空格可以使项目看起来是嵌套的，而不会创建可靠的列表级别。粘贴的内容还可以组合多个不兼容的编号定义。
如何修复它
- 选择受影响的项目并应用 Word 的项目符号或编号控件。
- 使用 增加缩进 and 减少缩进 设置实际列表级别。
- Right-click a numbered item and choose the appropriate continuation option.
- 删除仅用于创建视觉间距的空段落。
- 当中间的段落真正结束列表时，拆分列表。
转换后，检查原始 Markdown 而不仅仅是预览：
1. Install the application.
2. Configure the project.
- Add the source directory.
- Set the output format.
3. Run the build.不同的渲染器接受不同的缩进宽度，因此请使用一致的空间并在目标平台中进行预览。
问题 3：表格损坏或难以阅读
为什么会发生
GitHub Flavored Markdown 表格代表一个矩形网格。Word表格可以合并行和列、嵌套表格、包含多个段落、定位图像以及应用没有标准管道表等效项的视觉对齐。
如何修复它
- 添加可用作标题的清晰第一行。
- 取消合并信息必须保持表格形式的单元格。
- 将长解释移至表格下方。
- 用单独的表格或列表替换嵌套表格。
- 尽可能删除单元格内的手动换行符。
- 将文字管道字符转义为
\|。
如果表格的列数对于手机屏幕来说太多，则对其进行重组通常比强制直接转换更好。将每一行变成一个小部分或按主题拆分表格。
对于语法和对齐规则，请使用 Markdown 表格参考.
问题 4：图像丢失
为什么会发生
Markdown 需要一个单独图像文件的路径。WordToMD 包支持具有相对路径的嵌入图片，但浮动形状、图表、SmartArt、标题和一些旧格式仍可能被省略。
如何修复它
- 尝试 Markdown + 图像 ZIP 下载或使用专用的Word Image Extractor。
- 将资产放入
images/目录。 - 重命名通用文件，例如
image4.png. - 添加相关引用和有意义的替代文本。
- 在最终存储库、编辑器或站点中预览。
完整的过程包含在 带有图像的Word到 Markdown.
问题 5：文本框、SmartArt、图表或侧边栏消失
为什么会发生
这些对象位于 Word 页面上，而不是在主文档流中表示为普通段落。Markdown 没有基于坐标的页面画布，提取可见文本可能无法保留其预期的阅读顺序。
如何修复它
在转换之前将基本文本从浮动对象中移出：
- 将文本框警告转换为一个以
Warning:. - 将 SmartArt 图表导出为 SVG 或 PNG 并添加易于理解的文本说明。
- 将重要的图表结论转换为段落或小数据表。
- 将侧边栏内容移至描述性标题下。
当对象传达基本指令时，不要仅依赖屏幕截图。也保留文本中的含义。
问题 6：代码示例丢失栅栏或格式
为什么会发生
Word 通常将代码存储为具有等宽字体、背景底纹或自定义段落样式的普通文本。这些视觉属性并不总是指示文本是内联代码、命令还是多行程序。
如何修复它
转换后，将多行样本包装在围栏块中并自行添加语言标识符：
```javascript
function convert(document) {
return document.toMarkdown();
}
```对短命令和标识符使用内联反引号。检查样本内的反引号不会过早关闭栅栏。的 Markdown 代码块指南 解释了更长的栅栏和语法突出显示标识符。
问题 7：脚注、注释或跟踪更改丢失
为什么会发生
评论和跟踪更改是审阅元数据，而不是普通的最终文档内容。脚注是一个单独的 Word 结构，并非所有 Markdown 方言都支持脚注。WordToMD 针对最终可见文档进行了优化，而不是保留完整的编辑历史记录。
如何修复它
转换前：
- 保存一份未受影响的档案副本。
- 解决包含决定或指示的所有评论。
- 故意接受或拒绝跟踪的更改。
- 将重要的审稿人注释移至正文中。
- 决定目标如何处理脚注。
对于复杂的学术笔记、引文或修订工作流程， Pandoc 通常更合适。在采用迁移方法之前测试代表性文档。
问题 8：链接丢失或指向错误的位置
为什么会发生
蓝色下划线文本可能是普通格式而不是超链接。内部 Word 书签和交叉引用还依赖于当标题变为 Markdown 锚点 ID 时可能会发生变化的目标。
如何修复它
- 在 Word 中，使用 插入 → 链接 并验证实际地址。
- 将本地驱动器链接替换为存储库或 Web 目标。
- 转换后，单击每个外部链接。
- 使用目标平台的标题锚规则重建内部链接。
- 注意 URL 中意外包含的尾随标点符号。
对于可移植的结果，请使用描述性链接文本，而不是“单击此处”等短语。
问题 9：转换器产生空输出
为什么会发生
空结果通常意味着该文件在正常文档流中不包含可转换文本，不是有效的 .docx，或有内部腐败。扫描的页面、全页屏幕截图、画布和链接的对象对于人来说可能看起来像文档，但只包含很少的普通文本。
如何修复它
按此顺序进行操作：
- 确认文件名结尾为
.docx，不是.doc,.odt,.rtf，或重命名的 PDF。 - 在 Word 或 LibreOffice 中打开文档并保存新的
.docx副本。 - 将一个可见段落复制到新的空白文档中并进行测试。
- 如果源仅是图像，请在 Markdown 转换之前使用 OCR。
- 如果简单测试可以转换，请将内容分部分移至干净文档中，直到隔离有问题的对象。
修复时切勿覆盖唯一的源文件。
问题 10：Unicode 字符渲染不正确
为什么会发生
WordToMD 保留 Unicode 文本，包括中文、阿拉伯语、表情符号、智能标点符号和重音字符。如果字符在输出面板中看起来正确，但在保存或发布后出现错误，则问题通常是编辑器、文件编码、字体覆盖或目标渲染器。
如何修复它
- 将 Markdown 保存为 UTF-8。
- 避免传统的“ANSI”编码。
- 使用涵盖所需书写系统的字体。
- 构建网站时将 HTML 页面字符集设置为 UTF-8。
- 在最终布局中测试从右到左的段落。
- 仅当您了解隐形方向标记的功能时才删除它们。
不要仅仅为了解决配置错误的渲染器而音译或替换字符。
问题 11：转换缓慢或浏览器选项卡无响应
为什么会发生
本地转换使用当前设备的内存和处理能力。一个 .docx 即使只包含几页，也可能很大。移动浏览器和具有许多打开选项卡的设备的可用内存较少。
如何修复它
- 将嵌入的图片压缩到重复的 Word 文件中。
- 删除未使用或重复的媒体。
- 在逻辑章节边界处拆分大文档。
- 关闭内存密集型选项卡和应用程序。
- 尝试使用当前的桌面浏览器。
- 在本地使用 Pandoc 进行非常大或重复的转换。
WordToMD 接受最大 50 MB 的文件，但保持在该限制以下并不能保证在每台设备上具有相同的性能。
问题 12：旧的 .doc 文件被拒绝
为什么会发生
.doc and .docx 是不同的格式。年龄较大的 .doc 格式为二进制；更改文件扩展名不会转换其内容。
如何修复它
在 Microsoft Word 或 LibreOffice 中打开文件并选择 另存为 → Word 文档 (.docx). Then convert the new file. If the document is important, keep the original .doc 作为存档，直到检查新文件和 Markdown。
更好的预检流程
对于定期转换的文档，每次都使用相同的印前检查：
在 Word 中
- 使用内置标题样式。
- 使用真实列表控件。
- 简化合并和嵌套表。
- 解决跟踪的更改和评论。
- 将重要文本移出浮动对象。
- 删除未使用的媒体并压缩大图像。
- 确认超链接。
- 保存干净
.docx副本。
在 WordToMD 中
- 并排查看文档预览和可编辑 Markdown。
- 出现转换注释时将其打开。
- 检查每个元素类型的第一个实例。
- 直接在输出面板中更正简单问题。
- 在离开页面之前下载。
在目的地
- 预览渲染的 Markdown。
- 测试标题锚点和链接。
- 在窄屏幕上检查表格。
- 验证图像路径和替代文本。
- 确认代码围栏和语言标签。
- 搜索本地文件路径、占位符文本和未解决的审阅注释。
何时停止故障排除并更换工具
当任务是具有标准结构的快速、私密、单文档转换时，请使用 WordToMD。当您需要时，切换到 Pandoc 或自定义迁移管道：
- 自动媒体提取；
- 可重复的批处理；
- 学术引文或方程式；
- 自定义样式映射；
- Lua 过滤器或其他转换；
- CI/CD 内的转换；
- 复杂文档功能的详细处理。
更换工具并不是失败。当源文档的复杂性超过目标格式时，这通常是正确的响应。
FAQ
我应该修复 Word 文档还是编辑 Markdown？
当重复出现相同的结构错误时修复 Word 文档或将再次转换文件。当问题是孤立的或特定于目标时，编辑 Markdown，例如添加标题、标注、代码围栏语言或图像路径。
为什么 Markdown 预览看起来与 GitHub 或 Obsidian 不同？
Markdown 是一系列相关方言。表格、脚注、标注、任务列表、wiki 链接和原始 HTML 可以以不同的方式呈现。将 WordToMD 预览视为结构检查并在其真实目标中测试最终文件。
转换注释可以告诉我丢失的所有内容吗？
没有自动警告系统可以推断出 Word 文档中的每个视觉意图。使用转换注释作为线索，然后比较每个重要内容类型的源代码、Markdown 和最终呈现。
隔离损坏元素的最快方法是什么？
创建副本并删除一半内容。再次测试，然后继续测试仍然失败的一半。这种“划分并测试”的方法很快就缩小了问题的范围，而无需修改原来的内容。
结论
一旦您区分视觉格式和文档结构，大多数 Word 到 Markdown 的问题就变得可以预测。从第一个不正确的元素开始，在小测试中纠正它，并确定修复是否属于 Word、Markdown 还是目标平台。使用 WordToMD 对于快速本地转换， 格式指南 用于源准备，而 Pandoc 当工作需要更可编程的管道时。