OneNote笔记迁移5步搞定：onenote-md-exporter无损导出Markdown完整教程

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

onenote-md-exporter 是一款运行在 Windows 上的开源命令行工具，用于把 OneNote 笔记本整体导出为 Markdown 或 Joplin 原始目录格式。如果你正在考虑把多年笔记迁到 Obsidian、Joplin 这类 Markdown 生态，或者只是想给笔记做一份开放格式的本地备份，它就是为你准备的。

你的笔记是不是也困在这样的"围城"里？🏰

在决定换工具之前，先看看自己有没有中过这些招：

• 格式被锁死：复杂表格、嵌入文件换个平台就显示异常，很多导出方法只能保住七成内容
• 层级被压扁：笔记本→分区→子分区→页面的完整结构，导出后变成一摞平铺文件
• 链接全失效：笔记里的 OneNote 内部链接迁过去就变成死链，知识网络直接断掉
• 隐私有顾虑：在线转换工具要上传整本笔记，等于把家底交到别人手里

onenote-md-exporter 的定位很朴素：全程本地处理，数据不出这台电脑。它通过 OneNote 和 Word 的官方接口读取原始数据，再由 Pandoc 引擎做格式转换，最后用正则规则修一遍排版瑕疵，目标是保住 95% 以上的结构与格式。工具作者自己也在文档里反复提醒"导出前先备份"，这种克制反而让人放心。

先别急着装：onenote-md-exporter 的环境要求清单 ✅

动手前花两分钟核对三件事，能省掉后面大半的报错：

需要说明的是，商店版 OneNote 无法被这个工具调用，密码保护的分区如果不提前解锁也不会导出——这两条是它已知的边界，选型时心里有数就行。

5步完成第一次导出：onenote-md-exporter 上手流程 📦

1. 拿到程序：克隆仓库编译，或直接下载发布包

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

2. 补齐 Pandoc：进入src/OneNoteMdExporter/pandoc/目录，把pandoc-3.8.3-windows-x86_64.zip解压，让pandoc.exe落在该目录下。漏掉这步会直接报"找不到 pandoc.exe"
3. 预热 OneNote：先启动 OneNote，确认要导出的笔记本已加载并完成同步
4. 运行程序：双击OneNoteMdExporter.exe，按提示选择笔记本编号（输入 0 导出全部），再选格式——1是 Markdown，2是 Joplin 原始目录
5. 喝杯咖啡等着☕：导出结束会自动打开导出文件夹，中途可随时输yes打开appSettings.json调参数

命令行模式同样支持，后面批量脚本就用它：

OneNoteMdExporter.exe --notebook "技术笔记" --format 1 --no-input

常用参数有--section（只导某个分区）、--page（只导某一页）、--all-notebooks（忽略笔记本名，全部导出）、--ignore-errors（遇到坏页也继续）。想了解全部参数，运行OneNoteMdExporter.exe --help即可。

三处关键配置：导出结果由你说了算 ⚙️

appSettings.json是控制导出行为的核心，新手只需要关心三组开关。

① 页面层级怎么摆（ProcessingOfPageHierarchy）

• HierarchyAsFolderTree：父页面变成子页面的文件夹，默认值，层级一目了然
• HierarchyAsPageTitlePrefix：把父页面名拼进文件名前缀，适合目录不能有太多子文件夹的情况
• IgnoreHierarchy：完全忽略父子关系，最扁平

② OneNote 内部链接怎么处理（OneNoteLinksHandling）

• ConvertToWikilink：转成[[页面名|显示文字]]，Obsidian 用户首选
• ConvertToMarkdown：转成标准文字，Joplin 用户推荐
• KeepOriginal：保留onenote://原样
• Remove：删掉链接只留文字

③ 图片和附件放哪（ResourceFolderLocation）

• RootFolder：所有资源集中存到导出根目录的resources文件夹，适合大量图片的场景
• PageParentFolder：资源放在各自 Markdown 文件旁边，单文件自包含

再加一个AddFrontMatterHeader，开启后每页自动生成带标题和创建、修改时间的 YAML 头，方便 Obsidian 检索：

{ "ProcessingOfPageHierarchy": "HierarchyAsFolderTree", "OneNoteLinksHandling": "ConvertToWikilink", "ResourceFolderLocation": "RootFolder", "AddFrontMatterHeader": true, "PanDocMarkdownFormat": "gfm" }

一个真实场景：把1200篇团队笔记批量迁到 Obsidian 🏢

假设你们团队要把"项目文档"笔记本整体搬到 Obsidian，还要照顾到以后定期增量更新：

1. 先跑一次完整导出，ConvertToWikilink保证双链可用
2. 用批处理脚本把多个笔记本串起来，实现无人值守

@echo off for %%i in (项目文档 会议记录 客户资料) do ( echo 正在导出笔记本：%%i OneNoteMdExporter.exe --notebook "%%i" --format 1 --no-input )

日常新增内容后，重新对单个笔记本执行同一命令即可覆盖导出，配合--ignore-errors即使个别页面有问题也不会中断整批任务。导出完成记得抽查：文件夹层级是否与原笔记本一致、页面数量是否对得上、图片引用是否是相对路径。

三个高频报错与最快解法 🔧

报错一：System.Runtime.InteropServices.COMException通常是本机 OneNote/Office 安装有问题。最快的办法是重装 Office；如果不想折腾，可以在 OneNote 里用"文件→导出→OneNote 包"把笔记本存成.onepkg，换一台干净的电脑导入后再导一次（详细步骤见doc/notebook-onepkg-export.md）。

报错二：导出后图片丢失或损坏八成是笔记本没有完整同步到本地。去 OneNote 的"文件→选项→同步"里勾选"下载所有文件和图像"，强制同步后重新导出。

报错三：提示 pandoc.exe 找不到回到第 2 步，确认压缩包已经解压、exe 确实在pandoc/目录下。另外工具和 OneNote 都要以普通权限启动，不要用管理员身份跑。

效果到底行不行？两张表说明问题 📊

先看和传统 ENEX 迁移路线的对比（详见doc/migration-to-joplin.md）：

再看常见内容类型的支持情况：

架构上也值得说一句：它先通过 Interop API 把页面转成 DocX，再用 Pandoc 翻译成 Markdown，最后跑一遍正则后处理修复空行、多余引用块等小瑕疵，全程不依赖微软云服务。Joplin 迁移的完整流程可以看doc/migration-to-joplin.md。

想贡献或深入了解？入口都在这 🌱

• 翻译多语言：src/OneNoteMdExporter/Resources/下已有中、英、法、西四个语言文件，照着trad.en.json翻译一份提交即可
• 新增导出格式或设置项：doc/contribute.md写清了从ExportServiceBase继承实现的路子
• 发布流程与测试样例：仓库内的TestNotebook.onepkg和sample/目录可以直接拿来练手

工具本身遵循 GPL-3.0 协议，免费开源，无任何使用费用。

如果你手里正好有一本攒了多年的 OneNote 笔记本，现在就是动手的最佳时机：先跑通一个小测试本，熟悉层级和链接的配置手感，再挑最重要的笔记本正式迁移。一次导出，换来的是完全属于你、随时可读、随处可搬的 Markdown 知识库——这个投入，值得现在就开始。

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