OneNote 导出 Markdown 零门槛迁移：两千篇笔记，一个下午搬进 Obsidian
【免费下载链接】onenote-md-exporterConsoleApp to export OneNote notebooks to Markdown formats项目地址: https://gitcode.com/gh_mirrors/on/onenote-md-exporter
我的 OneNote 里躺着两千多篇旧笔记，一直想迁到 Obsidian 却不敢动手。直到我找到本地命令行工具 onenote-md-exporter——它能把 OneNote 笔记完整导出为 Markdown，分区层级、图片附件、内部链接全都保住，全程不联网。这篇手记，写给同样攒了一柜子笔记的你。
先跑通再研究：五分钟让第一份 Markdown 出炉
这一节只做一件事：把工具装好、让最小导出跑起来，先看到成果再谈别的。前置条件一句话——Windows 10 及以上，OneNote 2013 及以上（微软商店版不支持），Word 2013 及以上。然后按四步走：
- 把仓库拿下来。命令行执行
git clone https://gitcode.com/gh_mirrors/on/onenote-md-exporter，这是唯一一次联网，之后全程离线。 - 给 Pandoc 腾个位置。进入
src/OneNoteMdExporter/pandoc/目录，把pandoc-3.8.3-windows-x86_64.zip解压，让pandoc.exe和压缩包待在同一个文件夹。它是后面的格式转换引擎，缺了会直接报错。 - 把 OneNote 打开。确认要导出的笔记本已加载并完成同步。程序读的是实时状态，笔记本没打开等于空跑。
- 开跑。偷懒就双击
OneNoteMdExporter.exe，它会列出本机所有笔记本，让你勾选、选格式、改高级设置；想无人值守就用命令行：
OneNoteMdExporter.exe --notebook "我的笔记本" --format 1 --no-input人话翻译：--format 1是 Markdown 文件夹格式（2是 Joplin 原始目录格式），--no-input表示全自动、不需要任何交互。跑完程序会自动弹出导出文件夹，你会得到类似这样的结构——分区是文件夹、页面是.md、图片附件统一收在resources目录里，Markdown 内部用相对路径引用，放进 Obsidian 仓库就能直接用，不用再改任何路径。
我的笔记本/ ├─ 工作项目/ │ ├─ 需求文档/ │ │ ├─ 需求评审.md │ │ └─ 技术方案.md │ └─ 周报.md ├─ 生活随笔.md └─ resources/ ├─ 截图1.png └─ 附件.pdf看到这份目录，你大概和我一样好奇：它凭什么能保住层级、保住图片？其实原理三句话就够讲完。
三句话讲透原理：一台本地的"翻译流水线"
这一节不堆术语，只讲你真正需要理解的 20%。
- 数据一步都不出电脑。工具通过 OneNote 和 Word 的官方 COM 接口直接读本机内容，没有"上传到网页再下载"的中间环节。
- 双引擎接力，谁擅长谁上。先借 OneNote 把每页内容导出成 DocX 中间稿，再由 Pandoc 把 DocX 翻译成 Markdown——就像先把原稿誊抄成标准格式，再交给专门的翻译官转成目标语言，比单步转换稳得多。
- 最后再校一遍稿。程序会对 OneNote 页面 XML 做预处理、对生成的 Markdown 跑一轮正则后处理，把多余的换行、误生成的引用块这类"毛刺"修掉。
三层各司其职，所以普通表格、复杂表格、图片、附件、大纲层级，都能端端正正地落到 Markdown 里。原理清楚了，接下来按你的目的地调参数——这才是让导出效果拉开差距的地方。
按平台调参：三组配置方案照着抄
这一节给出三套可直接套用的配置组合，按目的地选一组就行。所有开关都写在 exe 旁边的appSettings.json（源码里对应src/OneNoteMdExporter/appSettings.json）。
| 方案 | 适合谁 | 关键配置 |
|---|---|---|
| Obsidian 双链方案 | 去 Obsidian，想要双向链接 | OneNoteLinksHandling设ConvertToWikilink，ProcessingOfPageHierarchy保持HierarchyAsFolderTree，AddFrontMatterHeader设true |
| Joplin 原样导入方案 | 去 Joplin，想保留标签和页面顺序 | 命令行--format 2，OneNoteLinksHandling换ConvertToMarkdown，PanDocMarkdownFormat保持gfm |
| 全量备份方案 | 想批量导出全部 OneNote 笔记 | 加--all-notebooks参数，它会忽略--notebook，挨个处理 |
三组的实际效果：
- Obsidian 双链方案：OneNote 内部链接会变成
[[页面标题|显示文字]]的双链，双向链接开箱即用；每篇笔记自动带上含创建时间、更新时间的 YAML 头，方便后期检索。 - Joplin 原样导入方案：导出后在 Joplin 里走「文件 → 导入 → RAW - Joplin Export Directory」选择导出目录即可，分区层级变成子笔记本、页面顺序原样保留。更细的对照说明在 doc/migration-to-joplin.md。
- 全量备份方案：命令行示例
OneNoteMdExporter.exe --all-notebooks --format 1 --no-input，适合定期给整个笔记库做一份 Markdown 格式的离线备份。
另外两个常用的旋钮：嫌 Windows 路径过长报错，就把MdMaxFileLength调小一点；想让图片附件贴近各自的页面，把ResourceFolderLocation从RootFolder改成PageParentFolder。
避坑速查：四个高频问题，现象和答案都给你
这一节是问答式速查表，遇到问题先来这里翻。
问：双击后立刻报System.Runtime.InteropServices.COMException，怎么办？答：这是程序没能和 OneNote 组件握手，通常是本机 Office 安装出了问题。最省事的解法不是重装 Office，而是按 doc/notebook-onepkg-export.md 把笔记本导出成.onepkg包，换一台干净的电脑导入后再导出，效果一样、风险更低。
问：导出的图片是坏的或直接没了？答：多半是 OneNote 本地根本没缓存这些图片。到「文件 → 选项 → 同步」勾选"下载所有文件和图像"，强制同步一次再重新导出，基本都能救回来。
问：密码保护的分区导出来是空的？答：锁定状态的内容程序读不到。导出前手动解锁一次，再跑就没问题。
问：报错提示文件路径过长？答：某个页面标题太长导致的。把appSettings.json里的MdMaxFileLength调小，从源头避开 Windows 的路径长度限制。
最后提醒一句：手写笔迹目前不支持转换，这是工具明确的边界，涉及手写内容的页面导出前要有心理准备。任何报错都可以先翻导出目录下的logs.txt，里面的信息比弹窗多得多。
照着这张清单做，一次搬完
这一节把从零到一的流程收拢成一张清单，照做就行。
- 克隆仓库，把
pandoc.exe解压到src/OneNoteMdExporter/pandoc/目录下； - 打开 OneNote，等要导出的笔记本同步完成，先拿一个小笔记本试跑一遍；
- 对照上面的表格，按目的地（Obsidian 还是 Joplin）调好
appSettings.json； - 导出后随机抽查十几篇带表格、带图片的笔记，确认质量再全量导出；
- 报错先看
logs.txt，携带日志去项目里提问，或直接参与改进。
想帮这个工具变得更好，翻译和贡献指南都在 doc/contribute.md，照着做就行。
迁移这件事没有想象中那么吓人。最难啃的部分——格式转换、层级保留、图片归位——工具已经替你处理完，你只需要挑一个不忙的下午，把清单走一遍，然后在新编辑器里重新遇见那些旧文字。
【免费下载链接】onenote-md-exporterConsoleApp to export OneNote notebooks to Markdown formats项目地址: https://gitcode.com/gh_mirrors/on/onenote-md-exporter
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
