OneNote导出Markdown完整教程：onenote-md-exporter从入门到精通

OneNote导出Markdown完整教程：onenote-md-exporter从入门到精通

【免费下载链接】onenote-md-exporterConsoleApp to export OneNote notebooks to Markdown formats项目地址: https://gitcode.com/gh_mirrors/on/onenote-md-exporter

本文是一份关于 OneNote 转 Markdown 的完整操作指南，详细介绍开源工具 onenote-md-exporter 的安装步骤、首次导出流程、进阶配置策略与常见问题排查，帮助你把 OneNote 笔记本无损迁移到 Obsidian、Joplin 等现代笔记平台。

周一早上，老张对着屏幕发呆。公司要求把团队三年的 OneNote 项目文档迁到 Obsidian，他试过复制粘贴——表格全散架，几百个页面成了扁平的一堆文件；试过在线转换工具——文档传到别人的服务器，合规部门第一个不答应。折腾两天，进度为零。

这个场景你可能不陌生。OneNote 的数据锁定在自己的格式里，分区、页面层级、内部链接、图片附件，哪一样都让人头疼。这篇文章围绕一个免费开源工具onenote-md-exporter（一款在 Windows 上运行的命令行程序，能把 OneNote 笔记本批量导出为 Markdown）讲透整条迁移路径，从安装到进阶配置，一次讲完。

为什么 OneNote 迁移这么麻烦

先看清问题出在哪：

• 格式封闭：OneNote 的页面内容存放在私有数据库中，普通工具读不出来。
• 层级复杂：笔记本→分区组→分区→父页面→子页面，五层结构在导出时很容易被压扁。
• 内部链接：页面间用onenote://协议互相引用，换平台后全部变成死链。
• 资源分散：图片、附件内嵌在页面 XML 里，手动导出必然丢位置。

手动方案（复制粘贴、PDF 批量打印、ENEX 中转）各有各的坑。而 onenote-md-exporter 走的是另一条路：直接调用 OneNote 和 Word 的官方 COM 接口提取原始内容，再交给Pandoc（业界标准的文档格式转换引擎）完成 DocX 到 Markdown 的转换，全程在本地运行，不上传任何数据。

三步完成安装与首次导出

前置条件（缺一不可）：

• Windows 10 及以上系统
• OneNote 2013 及以上版本（商店版不支持）
• Microsoft Word 2013 及以上版本
• .NET 运行时环境

第一步：获取程序

git clone https://gitcode.com/gh_mirrors/on/onenote-md-exporter

也可以直接下载发布包解压，得到OneNoteMdExporter.exe。

第二步：准备 OneNote

先启动 OneNote，确认要导出的笔记本已经完整加载并完成同步。这一步很关键，漏掉它会出现"导出后图片丢失"的后续麻烦。

第三步：运行导出

双击OneNoteMdExporter.exe，按提示操作：

1. 从列表中选择笔记本（输入 0 代表导出全部）；
2. 选择导出格式：1为 Markdown，2为 Joplin 专用格式；
3. 询问是否修改配置时输入y，会用记事本打开appSettings.json，首次使用建议保持默认；
4. 去喝杯咖啡 ☕，等待期间程序会逐页转换，导出完成后自动打开输出文件夹。

命令行模式适合批量场景，核心参数如下：

# 导出指定笔记本为 Markdown OneNoteMdExporter.exe --notebook "工作笔记" --format 1 --output "D:\笔记备份" # 导出全部笔记本为 Joplin 格式 OneNoteMdExporter.exe --all-notebooks --format 2 --no-input

常用参数：--section指定分区、--page指定页面、--ignore-errors跳过出错页面继续导出、--debug开启调试日志。完整说明运行OneNoteMdExporter.exe --help查看。

链接处理策略怎么选

OneNote 内部链接的转换，是迁移后知识网络能否复活的胜负手。程序通过OneNoteLinksHandling参数提供四种策略：

配置在 src/OneNoteMdExporter/appSettings.json 中修改，保存后重新运行即可生效。

三种典型场景的配置方案

场景一：Obsidian 双链笔记迁移

Obsidian 最大的价值是双链和知识图谱，配置要往"保持结构、生成双链"上靠：

{ "ProcessingOfPageHierarchy": "HierarchyAsFolderTree", "ResourceFolderLocation": "PageParentFolder", "OneNoteLinksHandling": "ConvertToWikilink", "AddFrontMatterHeader": true, "UseHtmlStyling": true }

HierarchyAsFolderTree会把父子页面还原成文件夹嵌套，图片跟随页面存放，方便整个文件夹拖进 Obsidian 库。开启AddFrontMatterHeader后，每页开头会生成包含创建时间、更新时间的 YAML 元数据头，Obsidian 可以据此做时间线视图。

场景二：Joplin 平台迁移

Joplin 有自己的导入格式，选择2（Joplin Raw Directory）导出后，在 Joplin 中执行"文件 > 导入 > RAW - Joplin 导出目录"即可。相比先转 ENEX 再导入的传统路线，这种直连方式能保住分区层级和页面顺序（详细对比见 doc/migration-to-joplin.md）。

{ "ProcessingOfPageHierarchy": "HierarchyAsFolderTree", "ResourceFolderLocation": "RootFolder", "OneNoteLinksHandling": "ConvertToMarkdown", "PanDocMarkdownFormat": "gfm" }

资源统一放在根目录resources文件夹，Joplin 导入后会自动识别。

场景三：通用 Markdown 归档

只想把笔记变成永久可读的开放格式，追求最小依赖：

{ "ProcessingOfPageHierarchy": "IgnoreHierarchy", "OneNoteLinksHandling": "Remove", "AddFrontMatterHeader": false, "UseHtmlStyling": false }

IgnoreHierarchy忽略页面层级，所有页面平铺在分区目录下；UseHtmlStyling关闭后，字体颜色、背景色不再生成 HTML 标签，输出更纯净。

三种方案横向对比：

最常见的报错及解法

报错一：COMException 初始化失败

Unhandled exception. System.Runtime.InteropServices.COMException

程序无法与 OneNote 通信。按顺序排查：

1. 确认 OneNote 已启动并登录 Microsoft 账户；
2. 以管理员身份运行命令提示符再执行程序；
3. 检查 Office 安装完整性，必要时修复；
4. 换台电脑试：在 OneNote 中"文件 > 导出 > 笔记本 > OneNote 包"，把生成的.onepkg文件在另一台电脑导入后导出（流程见 doc/notebook-onepkg-export.md）。

报错二：导出后图片大量丢失

多数是同步未完成。在 OneNote 中打开"文件 > 选项 > 同步"，勾选"下载所有文件和图像"，强制同步后再导出。也可以在配置里把KeepOneNoteTempFiles设为true保留中间 DocX 文件，便于定位是哪一步丢的。

报错三：文件名过长导致路径错误

页面标题动辄七八十字，文件系统路径会超限。调低配置里的PageTitleMaxLength和MdMaxFileLength（默认都是 50），标题超出部分会被自动截断。

导出质量能到什么程度

从功能支持表看（完整清单见项目 README），大部分常用元素都有保障：

需要注意：跨笔记本链接和指向分区的链接会被移除；UseHtmlStyling开启时高亮不会转成==语法。这些都是有意的取舍，导出后花几分钟抽查几个复杂页面即可。

与生态工具协同的完整工作流

• Obsidian：按场景一导出后，把文件夹复制进库目录，刷新即可。双链会自动生成，配合图谱视图可以重建知识网络。
• Joplin：按场景二导出，用 RAW 导入功能完成迁移。
• 批量自动化：在 PowerShell 中循环调用--all-notebooks，配合--ignore-errors即可实现无人值守的定期备份。
• 长期归档：Markdown 是纯文本开放格式，任何编辑器都能打开，50 年后依然可读，这是 OneNote 私有格式给不了的保障。

收尾：三条核心结论与下一步行动

1. 本地处理、隐私无忧：数据全程不离开电脑，不依赖微软云服务，适合企业文档迁移。
2. 结构保留是最大卖点：分区层级、页面父子关系、内部链接都有对应的处理策略，这是复制粘贴和 ENEX 中转做不到的。
3. 配置决定体验：动手前先想清楚目标平台，对照上文三套配置选择，能省下大量返工时间。

建议的行动路径：先备份 OneNote 原始数据（务必！），再用一个测试笔记本跑通全流程，确认输出质量后，再对全量数据执行迁移。迁移完成不等于结束——记得在 Obsidian 或 Joplin 里逐个抽查链接和图片，把工具生成的 emoji 标签整理成自己的标签体系。

选一个周末下午，备份好数据，开始你的第一次导出实验。你会发现，把知识从 OneNote 里"解放"出来，比想象中简单。

【免费下载链接】onenote-md-exporterConsoleApp to export OneNote notebooks to Markdown formats项目地址: https://gitcode.com/gh_mirrors/on/onenote-md-exporter