OneNote 迁移实战终极指南：onenote-md-exporter 5 步完成笔记无损转换

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

深夜十一点，前端工程师阿哲盯着屏幕发愁：他在 OneNote 里攒了六年的八百多篇技术笔记，眼看就要随着公司回收 Office 账号一起消失。他试过复制粘贴，格式碎成一地；也试过在线转换工具，结果第一步就要求把整个笔记本上传云端，他犹豫了。直到有人向他推荐了 onenote-md-exporter——一款能在本地把 OneNote 笔记本完整导出为 Markdown 的命令行工具，这段迁移故事才终于迎来转机。

如果你也囤着几年的笔记不敢动，或者正打算从 OneNote 搬到 Obsidian、Joplin 这类现代笔记软件，这篇实战指南就是为你准备的。我们不谈虚的，从"为什么会踩坑"讲到"五步完成首次导出"，再到"不同身份的人怎么把工具用到极致"，一次讲透。

迁移前 vs 迁移后：差的不只是文件格式

先别急着操作。动工之前，我们先回答一个关键问题：为什么不能直接在 OneNote 里导出、再手动搬过去？

答案藏在下面这张对照表里。同样是"搬笔记"，用对工具和用手工搬运，体验完全是两回事。

一句话总结：手工搬运是在"搬家"，而这款工具是在"整栋楼平移"——楼层关系、房间里的家具摆设，尽量原样保留。

当然，"尽量"两个字背后藏着不少细节。听起来很美好？先别急着下结论，我们直接从零开始走一遍完整流程，你自己感受一下。

五步完成首次导出：从环境准备到看见成果

记住一个原则：先跑通，再优化。第一次别追求完美配置，用默认参数导出成功，就算迈过了最大的一道坎。

第 1 步：确认环境达标

onenote-md-exporter 是个 Windows 下的控制台程序，对你的电脑有三个基本要求：

• 操作系统：Windows 10 及以上
• OneNote：2013 或更高版本（注意：Windows 商店版不支持，请用桌面版）
• Word：2013 或更高版本

前两项好理解，为什么还要 Word？后面讲原理时会解释——它和 Pandoc 一起，是转换链路里的关键角色。先记住：这三样缺一不可。

💡 小贴士：发布版本是 .NET 10 的自包含程序，解压即用，通常不需要额外安装运行时。只有从源码自己编译时才需要准备开发环境。

第 2 步：拿到工具

两种方式任选其一：

• 懒人路线：直接下载最新发布的压缩包，解压到任意目录；
• 折腾路线：动手克隆源码自己构建：

# 克隆项目源码，适合想二次开发或自行编译的读者 git clone https://gitcode.com/gh_mirrors/on/onenote-md-exporter

无论哪条路，解压后请留意src/OneNoteMdExporter/pandoc/目录——里面有一个pandoc-3.8.3-windows-x86_64.zip压缩包。把它解开，让pandoc.exe与程序在同一目录下，否则后面的格式转换会罢工。

第 3 步：让 OneNote 做好准备

启动 OneNote，确认你要导出的笔记本已经加载、并且同步完成。

这一步看起来无关紧要，其实是最常见的翻车点：OneNote 的云端同步策略比较"佛系"，有些图片和附件只存了缩略图。如果本机没有完整内容，导出结果就会缺图少件。后面避坑部分还会专门讲它。

第 4 步：跑起来，选笔记本、选格式

直接双击运行OneNoteMdExporter.exe，它会列出检测到的所有笔记本，你输入编号即可选择。接着它会问你导出格式：

• 输入 1：Markdown 文件夹格式——适合 Obsidian、Logseq 这类通用 Markdown 编辑器；
• 输入 2：Joplin 原始目录格式——专门给 Joplin 用的，导入后连笔记层级都给你建好。

选完格式，程序会问你"要不要现在改设置"。第一次建议直接回车跳过，用默认值就好。

**然后呢？去冲杯咖啡。**☕ 导出期间程序会逐页处理，结束后会自动用资源管理器打开导出文件夹，让你第一时间看到成果。

第 5 步：认识你的导出结果

打开导出文件夹，你会看到这样的结构：

我的笔记本/ ├── 分区A/ │ ├── 父页面/ │ │ ├── 子页面.md │ ├── 普通页面.md │ └── resources/ # 图片与附件集中存放处 ├── 分区B/ │ └── ...

分区变成文件夹，页面变成.md文件，图片和附件集中放在resources目录，Markdown 里用相对路径引用它们。整个目录拿到任何 Markdown 编辑器里都能直接打开。

⚠️ 注意：默认配置下，页面在分区内的排序依赖文件名。如果顺序对你不重要，可以忽略；如果很在意，建议改用 Joplin 格式（它保留原始顺序）。

按需分层定制：基础、进阶、极致三种玩法

跑通只是第一步。想让导出结果"长得像你原来的笔记"，你得学会调参。所有配置都写在程序目录下的appSettings.json文件里（点击查看默认配置），分三个层次理解就够。

基础需求：三个参数解决 80% 的问题

绝大多数个人用户，改这三个就够了：

{ "AddFrontMatterHeader": true, // 每页开头加 YAML 元数据（标题、创建/修改时间） "ProcessingOfPageHierarchy": "HierarchyAsFolderTree", // 父页面作为子页面的文件夹 "OneNoteLinksHandling": "ConvertToWikilink" // 内部链接转成 [[Wiki链接]]，Obsidian 双链友好 }

• 想去 Obsidian 玩双向链接？把OneNoteLinksHandling设为ConvertToWikilink；
• 想去 Joplin？改成ConvertToMarkdown更合适；
• 什么都不想要，就想把链接删干净？设为Remove。

进阶需求：按场景挑着改

{ "ResourceFolderLocation": "RootFolder", // 所有图片附件集中放在根目录 resources 文件夹 "PanDocMarkdownFormat": "gfm", // 用 GitHub 风格 Markdown 语法 "UseHtmlStyling": true, // 允许用 HTML 保留字体颜色、背景色等样式 "IndentingStyle": "ConvertToBullets" // OneNote 缩进转成列表，观感最接近原笔记 }

ResourceFolderLocation有两个值：RootFolder（集中存放）和PageParentFolder（每个页面旁边各放一份资源）。图片多的笔记本用前者省心，想每个页面自成一体、方便单独分享时用后者。

UseHtmlStyling尤其值得注意：如果你用的编辑器支持 HTML（Obsidian、Joplin 都支持），务必开着，它能帮你保住字体颜色、背景色这些 Markdown 表达不了的东西。

极致需求：为大型笔记本兜底

{ "PageTitleMaxLength": 50, // 页面标题超长时自动截断，避免文件名过长 "MdMaxFileLength": 50, // 限制文件与文件夹名长度，防止路径超长报错 "PostProcessingRemoveQuotationBlocks": true, // 去掉 Pandoc 偶发产生的多余引用块 "MaxTwoLineBreaksInARow": true // 最多允许连续两个换行，版面更干净 }

这四个是"保险丝"级别的参数，平时不用动，等你遇到路径过长、空行过多这类问题再回来翻它们。

参数再好，最终还是要落到具体的人身上。下面这三个真实场景，或许你能在某个故事里看到自己的影子。

三个人的迁移故事：他们是这样用的

故事一：知识管理爱好者小鹿，把 1200 篇笔记搬进 Obsidian

小鹿是位产品经理，Obsidian 用了两年，却始终有一块心病：主力笔记还在 OneNote 里，两边割裂，检索全靠回忆。

她给自己定了个"三步走"计划。第一步，先用一个测试笔记本跑通流程，确认ProcessingOfPageHierarchy = HierarchyAsFolderTree下层级没塌；第二步，把OneNoteLinksHandling调成ConvertToWikilink，让旧笔记里的互链变成 Obsidian 的双链；第三步，开着AddFrontMatterHeader，让每篇笔记自带时间戳。

"第一次导出完，我打开 Obsidian 的图谱视图，看到几千个节点连成一片，当时就愣住了。"小鹿说，"那一刻才真正感觉，我的知识资产是自己的了。"

故事二：咨询公司 IT 负责人老周，三天搞定团队文档迁移

老周所在的团队有二十多人，笔记散落在"项目文档""会议记录""客户资料"等好几个笔记本里，要统一迁到团队知识库。

他的思路是"先集中、再分发"：把ResourceFolderLocation设为RootFolder，所有图片集中管理；然后用一个批处理脚本逐个笔记本导出，全程无人值守：

REM 批量导出多个笔记本，配合 --no-input 跳过交互，--ignore-errors 让单个失败不中断 for %%i in (项目文档 会议记录 客户资料) do ( OneNoteMdExporter.exe --notebook "%%i" --format 1 --no-input --ignore-errors )

"脚本跑完那晚我基本没管它，第二天早上来，三个笔记本整整齐齐躺在共享盘里。"老周的经验是：迁移团队知识库，最怕的不是慢，而是中断后没人盯着。

故事三：自动化爱好者大刘，把导出变成"下班自动执行"

大刘是运维出身，他不想每次手动点。他研究了命令行参数后发现，工具支持--notebook、--format、--section、--page等参数，甚至能精确到"只导出某个分区的某一页"。

他把自己的"学习笔记"笔记本做成一个计划任务，每周五 18:00 自动执行一次全量导出作为备份：

# 全自动备份：导出全部笔记本，无需任何交互输入 OneNoteMdExporter.exe --all-notebooks --format 1 --no-input

"数据安全这事儿，靠自觉靠不住，靠定时任务才靠得住。"大刘的这句话，值得每个笔记重度用户记下来。

三个故事都很顺利？别高兴太早。真实世界里，总有几个坑在前面等着你。

高频问题自查清单：遇到报错先看这里

Q1：一启动就报System.Runtime.InteropServices.COMException

这是最常见的报错，多半不是你操作的问题，而是本机 Office/OneNote 组件状态异常。按顺序排查：

1. 重启 OneNote 和 Word，再运行一次程序；
2. 确认你用的是 OneNote 桌面版，而不是 Windows 商店版；
3. 如果还不行，按这篇文档把笔记本导出成.onepkg包，换一台干净的机器导入后再导出。

Q2：导出后图片显示不出来 / 变成空白

十有八九是 OneNote 本地没有完整的图片文件。解决办法：

1. 打开 OneNote：文件 → 选项 → 同步，勾选"下载所有文件和图像"；
2. 强制同步一次笔记本；
3. 重新导出。

这条建议来自官方 FAQ，属于命中率最高的修复方案。

Q3：大型笔记本导出又慢又卡

大库的处理时间主要花在"逐页转格式"上。可以这样拆解：

• 先只导一个分区试试水，用--section参数控制范围，确认流程无误再全量导出；
• 给程序留足磁盘空间和内存，导出目录别放在快满的盘上；
• 导出期间别在 OneNote 里继续编辑笔记，避免文件占用冲突。

Q4：有些内容"消失"了？

先对照这张能力边界表，看消失的是不是本就支持的内容：

迁移前记得先解锁所有受密码保护的分区——这是最容易被忽略的一条。

搞清楚了边界，我们再往深挖一层：这套"无损转换"到底是怎么实现的？

背后的原理：一位翻译官和一位校对编辑

把 onenote-md-exporter 想象成一个三人翻译团队，你就能理解它的工作方式：

1. 读原文：它通过 OneNote 的 COM 接口，把每个页面的内容（本质是 XML 结构）读取出来，做一轮"预处理"——把折叠段落展开、记录字体颜色等细节；
2. 打草稿：把页面内容先转成临时的 DocX 文档——这就是为什么需要安装 Word；
3. 正式翻译：调用 Pandoc——那位"通用格式翻译官"，把 DocX 转成 Markdown；
4. 校对编辑：用一系列正则规则做后处理，修复格式转换产生的"错别字"，比如去掉多余的引用块、合并连续空行。

OneNote 页面 XML → 临时 DocX → Pandoc 转 Markdown → 正则后处理 → 最终 .md + 资源文件夹

整个过程完全在本地进行，不依赖微软云，这也是它敢承诺数据安全的底气所在。

💡 顺带一提：整套翻译流程是"读原文再转述"，所以 OneNote 里的层级结构、页面顺序这类"骨架"信息，理论上可以做到近乎无损地搬进 Markdown 生态。核心转换逻辑在 src/OneNoteMdExporter/Services/Export/ 目录下，感兴趣的读者可以去翻翻源码。

理解了原理，接下来就是把工具用到极致的时候了。

效率进阶：从"能用"到"好用"的四个技巧

技巧一：按需导出，别每次都全量跑

只想找一篇旧笔记？用--section限定分区，用--page精确到页面，几秒钟就出结果，不必为整本笔记本付等待时间。

技巧二：给 Joplin 用户一条捷径

如果你最终要去的是 Joplin，直接选格式 2（Joplin 原始目录），然后打开 Joplin：文件 → 导入 → "RAW - Joplin Export Directory"，选中导出文件夹即可。相比先导 ENEX 再导 Joplin 的绕路方案，这个流程能保住分区层级和页面顺序，细节对比见官方迁移文档。

技巧三：用测试笔记本降低试错成本

仓库里附带了一个样例笔记本 sample/TestNotebook.onepkg。正式迁移前，先用它或自己建的小笔记本跑一遍各种配置组合，确认效果再上真库，风险最小。

技巧四：导出后的质量检查清单

每次导出完成，花五分钟抽查三件事：

• 结构对不对：文件夹层级和原笔记本的分区、子分区是否一一对应；
• 内容全不全：随机抽 10% 的页面，重点看表格、图片、代码块；
• 链接灵不灵：点开几处内部链接，确认 Wiki 链接能跳转到目标页面。

顺便说一句：如果你用下来觉得不错，这个项目欢迎任何形式的参与——界面支持多语言，翻译文件放在 src/OneNoteMdExporter/Resources/ 目录；想提交新功能或导出格式，可以参照 doc/contribute.md 里的约定，把测试样例一起附上即可。

现在，轮到你了

回顾整篇文章，其实就一句话：onenote-md-exporter 帮你把 OneNote 迁移这件事，从"高风险、高成本的手工活"变成了"可重复、可验证的脚本活"。你的笔记不会再被单一生态锁死，你的知识资产从此有了开放的格式作为退路。

别等"有空再说"了。按下面这份行动清单，现在就动手：

1. 检查电脑上的 OneNote 和 Word 版本，确认是桌面版且不低于 2013；
2. 下载或克隆工具，解压 pandoc 压缩包到程序目录；
3. 用一个小型测试笔记本跑通首次导出，验证 Markdown 文件夹结构；
4. 按你的目标平台（Obsidian 选 Wiki 链接、Joplin 选 Markdown 链接）调整appSettings.json；
5. 全量导出前，记得先解锁所有密码保护的分区、确保图片已完整下载；
6. 导出完成后抽查质量，然后——把备份脚本加入你的定期任务清单。

知识迁移是场马拉松，但最艰难的一步永远是"开始"。工具已经就位，剩下的，交给你了。

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