OneNote 转 Markdown 终极指南：onenote-md-exporter 免费保住 95% 的笔记格式与层级

OneNote 转 Markdown 终极指南：onenote-md-exporter 免费保住 95% 的笔记格式与层级

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

如果你也和我一样，把好几年的笔记都堆在 OneNote 里，那么一定懂这种纠结：平台越来越封闭、迁移越来越难。onenote-md-exporter 就是这样一款专门解决OneNote 转 Markdown难题的开源命令行工具——它完全在本地运行，把笔记本、分区、页面的完整层级和绝大多数格式转换到通用 Markdown 文件，实测格式保留率超过 95%，全程免费、无需上传任何数据。

先说一个真实的迁移故事

小林上个月想把 OneNote 里存了 6 年的读书笔记搬到 Obsidian。他先试了 OneNote 自带的导出功能——得到的是一堆 HTML 文件，图片路径乱成一团，页面之间的互相引用全部失效。接着他又找到一家在线转换网站，页面倒是很漂亮，但第一步就要他把整个笔记本上传到对方服务器。面对私人的日记、扫描证件和银行卡记录，他果断放弃了。

后来他换了一条思路：本地离线转换。onenote-md-exporter 从读取数据到写出文件，全部在本机完成，不依赖任何云服务。一个周末的时间，他把 1200 多篇笔记完整迁入了 Obsidian，双向链接、文件夹层级、图片附件全部正常。这个故事想说明的其实是：迁移这件事，工具选对了，真的不难。

它和"传统导出"到底差在哪

传统导出方式之所以让人头疼，核心是丢三样东西——格式、层级、链接。我们来对比一下：

具体到内容上：简单表格会转成标准 Markdown 表格，复杂表格则保留为 HTML 表格；待办、星标等文字标签会变成表情符号，手绘内容会被压平成图片。这套"能转 Markdown 就转 Markdown、转不了就用 HTML 兜底"的策略，正是格式保留率高的关键。

开始之前：先确认这四件事

onenote-md-exporter 是 Windows 下的工具，环境要求并不高，但有两处容易踩坑，请先对照检查：

1. 操作系统：Windows 10 及以上版本；
2. OneNote：2013 及以上桌面版（注意：Windows 商店版不支持，因为它没有暴露 COM 接口）；
3. Word：2013 及以上版本（转换引擎依赖它）；
4. 笔记就绪：启动 OneNote，确认要导出的笔记本已加载并完成同步。

小提示：导出前先花一分钟做一次"文件 → 选项 → 同步 → 立即同步"，能避免后续一半以上的图片丢失问题。

安装与首次导出：三个步骤搞定

第一步：获取程序

克隆项目仓库：

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

进入src/OneNoteMdExporter/pandoc/目录，解压pandoc-3.8.3-windows-x86_64.zip，确保pandoc.exe与程序放在同一目录下，然后按项目说明编译或使用发布包得到OneNoteMdExporter.exe。

第二步：交互式首次导出

双击运行OneNoteMdExporter.exe，跟着提示走即可：

1. 程序会列出本机所有笔记本，输入对应编号回车；
2. 选择导出格式：输入1为 Markdown 文件夹格式，2为 Joplin 原始目录格式；
3. 询问是否修改配置时，输入y会用记事本打开appSettings.json；
4. 等待导出完成，程序会自动用资源管理器打开导出目录。

整个过程不需要写一行命令，非常适合第一次上手。

第三步：命令行批量操作

熟悉之后，可以用命令行参数实现无人值守。常用的参数如下：

# 导出指定笔记本为 Markdown 格式 OneNoteMdExporter.exe --notebook "我的笔记本" --format 1 --no-input # 导出全部笔记本 OneNoteMdExporter.exe --all-notebooks --no-input # 只导出某个分区或某个页面 OneNoteMdExporter.exe --notebook "我的笔记本" --section "读书笔记" --page "第一章"

--no-input表示不等待键盘输入，适合脚本化调用；--debug会输出详细日志；--ignore-errors可以让某个页面出错时继续导出剩余页面。想了解全部参数，运行OneNoteMdExporter.exe --help即可。

五个值得认真调教的配置项

所有配置都集中在程序目录下的appSettings.json里，以下是新手最该理解的五个参数。

1. ProcessingOfPageHierarchy：页面层级怎么摆

OneNote 里"父页面下套子页面"很常见，导出时如何处理由它决定：

• HierarchyAsFolderTree（默认）：父页面变成子页面的文件夹，如Section/父页面/子页面.md；
• HierarchyAsPageTitlePrefix：父页面名变成文件名前缀，如Section/父页面_子页面.md；
• IgnoreHierarchy：忽略页面层级，全部平铺。

2. OneNoteLinksHandling：内部链接怎么转

OneNote 的onenote://链接在其他平台都是死链，这个参数决定它们的归宿：

• ConvertToWikilink（默认）：转为[[页面标题|显示文字]]，Obsidian 用户首选；
• ConvertToMarkdown：转为文字标准格式，Joplin 更合适；
• KeepOriginal：保留原始链接；Remove：删除链接只留文字。

3. ResourceFolderLocation：图片附件放哪

• RootFolder（默认）：所有图片和附件集中在导出根目录的resources文件夹，目录清爽；
• PageParentFolder：每个 md 文件旁边各放一个资源文件夹，方便单页分发。

4. AddFrontMatterHeader：要不要 YAML 头

设为true时，每页开头会生成包含元数据的 YAML 头：

--- title: 页面标题 created: 2023-05-01T10:00:00 updated: 2024-12-31T18:30:00 ---

这些字段能被 Obsidian 等工具识别，方便按创建时间、更新时间检索。

5. PanDocMarkdownFormat：Markdown 语法口味

默认gfm（GitHub 风格）兼容性最好；如果你的编辑器支持更丰富的语法，也可以换成 Pandoc 支持的其他格式。另外UseHtmlStyling建议保持true，让字体颜色、背景色等样式以 HTML 形式保留下来。

两个高频场景的完整实操

场景一：1200 篇技术笔记迁入 Obsidian

需求：保留完整层级，支持双向链接，图片集中管理。

步骤：

1. 将OneNoteLinksHandling设为ConvertToWikilink；
2. 保持ProcessingOfPageHierarchy = HierarchyAsFolderTree；
3. 开启AddFrontMatterHeader = true；
4. 执行OneNoteMdExporter.exe --notebook "技术笔记" --format 1 --no-input。

效果：在 Obsidian 中直接打开导出文件夹即是一个完整仓库，父页面自动成为文件夹，图片集中在resources，[[双链]]可以直接跳转。实测一千多篇笔记半小时内即可导完，页面结构与原笔记本完全一致，日常检索效率大幅提升。

场景二：团队文档批量迁移到 Joplin

需求：多个项目笔记本一次性迁移，保留笔记本层级与页面顺序。

步骤：

1. 在导出格式中选择2（Joplin 原始目录格式）；
2. 执行OneNoteMdExporter.exe --all-notebooks --no-input一次性处理全部笔记本；
3. 在 Joplin 中通过"文件 → 导入 → RAW - Joplin Export Directory"选择导出目录。

效果：分区层级自动映射为 Joplin 的笔记本层级，页面顺序完整保留。相比官方推荐的"ENEX 中转"方案，不丢层级、附件还在原位置，迁移体验好了不止一个档次。

三个最常见的坑与解决办法

1. 启动就报 COMException

多半是本机 Office 组件注册出了问题。先确认你用的是桌面版 OneNote 而非商店版；不行就修复一次 Office 安装。最省事的办法是：在另一台电脑上把笔记本导出为.onepkg文件，再导入本机重新导出。

2. 导出后图片大面积丢失

十有八九是 OneNote 还没把图片下载到本地。打开"文件 → 选项 → 同步"，勾选"下载所有文件和图像"，强制同步一次再导出。若只有个别图片丢失，检查导出目录下的resources文件夹，确认 md 文件中引用的是相对路径。

3. 手写内容没了、加密分区是空的

这是工具的已知边界：手写笔迹无法转换，加密分区必须先在 OneNote 里解锁才能导出。导出前把加密分区解锁、让所有分区保持同步状态，能避免绝大多数"内容缺失"的误会。

外行也能看懂的转换原理

这个工具能在格式上如此能打，靠的是一条"三板斧"流水线：

1. 读：通过 OneNote 的 COM 接口读取笔记本结构和页面 XML，先做一轮预处理——展开折叠段落、保留字体与背景色；
2. 转：把每页渲染成 DocX 中间格式，再交给 Pandoc 转成你指定的 Markdown 语法；
3. 修：最后用一系列正则规则做后处理——修正图片引用、合并多余空行、清理误生成的引用块，确保输出干净。

全程在本机完成，不依赖微软云，也不向任何第三方发送数据。你甚至可以开着--debug看每一步的日志，安心程度拉满。

导出后的质量检查清单

完成迁移不等于万事大吉，花五分钟做一轮检查：

• 文件夹层级与 OneNote 中的结构是否一致，页面数量是否吻合；
• 随机抽查 10% 的页面，重点看表格、图片、链接三类内容；
• 打开几个含双链的页面，确认跳转正常；
• 检查resources文件夹，图片文件数量与页面中引用数是否匹配；
• 确认每页 YAML 头的创建/更新时间正确。

如果导出失败，程序会在同目录生成logs.txt日志文件——报 bug 时把这份日志和复现步骤一起提交，维护者才能快速定位问题。

现在就可以开始

onenote-md-exporter 是开源免费的，代码就摆在那里，你可以放心长期使用。给你的上手路径是：克隆仓库 → 解压 pandoc → 拿一个小测试笔记本试跑一遍 → 按上面的配置项调优 → 再正式迁移主笔记本。如果你在迁移中遇到问题，欢迎去项目 Issues 反馈，附上日志和复现步骤；也欢迎参与翻译和功能贡献，让这个工具帮助到更多人。

记住：迁移笔记不是一次性的冒险，而是一笔稳赚不赔的投资。你的知识资产值得一个更开放、更自由的家。

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