把攒了多年的 OneNote 笔记搬进 Obsidian，我只用了一条命令

把攒了多年的 OneNote 笔记搬进 Obsidian，我只用了一条命令

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

小宇的电脑里躺着一个"时间胶囊"：整整五年的 OneNote 笔记本，两千多篇笔记，从学生时代的课件到工作后的技术总结。去年他想把这些笔记迁到 Obsidian 时，试过复制粘贴、试过 OneNote 自带的导出，结果表格全部散架、图片路径全乱、层级变成一摊平铺的文件。直到有人向他推荐了onenote-md-exporter——一个在本地运行的命令行工具，能把 OneNote 笔记本完整导出为 Markdown 格式，适配 Obsidian、Joplin 等主流笔记软件。这篇记录，就是他的完整迁移手记。

它凭什么敢说"导出后几乎不用改"

小宇最初也是半信半疑，直到他搞懂了工具的三个关键设计，才明白为什么这次不一样。

第一，数据从头到尾不出你的电脑。它直接调用本机的 OneNote 和 Word 程序（官方 COM 接口）读取原始内容，整个过程不依赖任何云端服务。那些"把笔记上传到网页再下载"的在线转换工具，对存着客户资料和私人日记的人来说，光想想就脊背发凉。

第二，笔记本的"骨架"被完整保留。分区变成文件夹，分区组变成嵌套目录，子页面默认作为父页面的下级文件夹。导出的目录树和你在 OneNote 里看到的结构几乎一一对应，而不是把所有页面哗啦一下倒进同一个文件夹。

第三，它天生就是为 Obsidian、Joplin 这类 Markdown 编辑器设计的。内部链接可以转成[[双链]]格式，每篇笔记能自动加上带创建时间、更新时间的 Front Matter 头，还内置了 Pandoc 转换引擎来兜底复杂表格和格式。这几点组合起来，就形成了下面这个对比：

从下载到第一份 Markdown，照做就行

动手之前，先确认三件事：Windows 10 及以上、OneNote 2013 及以上（注意，不支持微软商店版）、Word 2013 及以上。都齐了，就跟着走。

第一步，拿到工具。在命令行里克隆仓库：

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

第二步，补上转换引擎。进入src/OneNoteMdExporter/pandoc/目录，把里面的pandoc-3.8.3-windows-x86_64.zip解压，让pandoc.exe和压缩包待在同一个文件夹。没有这一步，程序会找不到格式转换器。

第三步，让 OneNote 就位。启动 OneNote，确认要导出的笔记本已经加载并完成同步。程序是读实时状态的，笔记本没打开可不行。

第四步，开始导出。最简单的方式是直接双击运行OneNoteMdExporter.exe，它会列出本机所有笔记本，让你勾选要导出的对象、选择格式，还能现场调整高级设置。等它跑完，会自动弹出导出文件夹。

想要批量或无人值守，就用命令行，一次指定笔记本和格式：

OneNoteMdExporter.exe --notebook "我的笔记本" --format 1 --no-input

这里的--format 1是 Markdown 文件夹格式，--format 2是 Joplin 原始目录格式；--no-input表示全自动、不需要任何交互。导出完成后，你会得到类似这样的目录结构：

我的笔记本/ ├─ 工作项目/ │ ├─ 需求文档/ │ │ ├─ 需求评审.md │ │ └─ 技术方案.md │ └─ 周报.md ├─ 生活随笔.md └─ resources/ ├─ 截图1.png └─ 附件.pdf

页面是.md文件，图片和附件统一收在resources文件夹里，Markdown 内部用相对路径引用——放进 Obsidian 仓库就能直接用，不需要再改任何路径。

第一次运行，这些坑我先替你踩了

小宇第一次跑就报了System.Runtime.InteropServices.COMException，差点放弃。后来才知道这是程序没能和 OneNote 组件握手，常见原因就是本机 Office 安装有问题。这时候最省事的解法不是重装 Office，而是按doc/notebook-onepkg-export.md里的说明，把笔记本导出成.onepkg包，换一台干净的电脑导入后再导出 Markdown。效果一样，风险更低。

还有几个坑，提前知道能省下不少时间：

• 导出后图片是坏的？多半是 OneNote 本地根本没缓存图片。到「文件 → 选项 → 同步」里勾上"下载所有文件和图像"，强制同步一次再重新导出，基本就能解决。
• 密码保护的分区变空了？记得在导出前手动解锁，锁着的分区内容不会进入结果。
• 手写笔迹直接消失？这是工具明确的边界，手写内容不支持转换，导出前心里要有数。
• 文件名太长导致路径超限？笔记本里有标题超长的页面时，可以在配置里把MdMaxFileLength调小一点，从源头避免 Windows 路径过长的报错。

小宇跑顺之后，还总结出几个进阶技巧，你可以按需取用：

给 Obsidian 用的推荐组合：把appSettings.json里的OneNoteLinksHandling设为ConvertToWikilink（OneNote 内部链接变成[[双链]]，双向链接直接可用），ProcessingOfPageHierarchy保持HierarchyAsFolderTree（层级就是文件夹），AddFrontMatterHeader设为true（每篇笔记自动带上创建/更新时间，方便检索）。

给 Joplin 用的推荐组合：格式选 2，链接策略换成ConvertToMarkdown，导出后直接以"原始目录"方式导入 Joplin，标签和层级都能对上。

一次性导出所有笔记本：加个--all-notebooks参数，它会忽略--notebook，把所有笔记本挨个处理一遍：

OneNoteMdExporter.exe --all-notebooks --format 1 --no-input

至于它为什么转换得这么稳，小宇后来大致弄明白了：程序先通过 OneNote COM 接口把每页内容导出成 DocX，再用 Pandoc 把 DocX 翻译成 Markdown，最后跑一轮正则后处理修复格式毛刺。这种"双引擎 + 后处理"的思路，比他见过的任何单步转换都稳妥。

出发前，收好这份行动清单

如果你也动了迁移的心思，不妨按这个顺序来：

1. 克隆仓库，按上文把pandoc.exe解压就位；
2. 先拿一个最常用的小笔记本试跑，全程开着 OneNote 等它同步完成；
3. 对照appSettings.json里的配置项，按你要去的平台（Obsidian 还是 Joplin）调好链接策略；
4. 导出完成后随机抽查十几篇带表格、图片的笔记，确认质量；
5. 遇到报错先看同目录下的logs.txt，再带着日志去项目里提问或参与改进。

知识迁移从来不是一夜之间的事，但好消息是：最痛苦的那一步，onenote-md-exporter 已经帮你走完了。剩下的，就是打开 Obsidian，和那些老笔记好好重逢。😄

想深入了解 Joplin 迁移细节，可以翻翻doc/migration-to-joplin.md；想参与翻译或贡献代码，doc/contribute.md里有完整的指南。

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