OneNote 笔记迁往 Markdown 的本地化迁移实战：onenote-md-exporter 完整上手与批量导出指南

OneNote 笔记迁往 Markdown 的本地化迁移实战：onenote-md-exporter 完整上手与批量导出指南

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

很多人在 OneNote 里攒了上千条笔记，等到想换到 Obsidian、Joplin 这类基于 Markdown 的平台时，却发现「导出」这一步格外痛苦。onenote-md-exporter 是一款运行在 Windows 上的开源命令行工具，能把 OneNote 笔记本完整转换为 Markdown 格式，全程离线处理、保留层级结构与内部链接，是评估迁移方案或做笔记备份的首选工具。下面这份指南会带你从安装一路走到批量实战。

一、先解决一个问题：为什么 OneNote 的「导出」总是不省心

如果你曾经尝试迁移 OneNote 笔记，大概率遇到过下面这些状况：

• 格式走样：OneNote 自带的导出功能把复杂表格、折叠段落、字体颜色统统压扁，到了新平台变成一团乱码。
• 层级消失：笔记本 → 分区 → 页面组的完整结构，导出去后变成一长串平铺文件，再也找不回原来的脉络。
• 链接全部失效：笔记里大量onenote://内部链接，换平台后全部变成死链。
• 隐私顾虑：在线转换网站需要把整个笔记本上传到别人的服务器，敏感内容根本不敢传。

onenote-md-exporter 的定位就是解决这些痛点：它借助 OneNote 与 Word 的 COM 接口读取原始数据，再经 Pandoc 完成 DocX 到 Markdown 的转换，最后用正则后处理修复格式细节。整个过程不依赖任何云端服务，数据始终留在本机。

二、它凭什么值得一试：与常见方案的能力对比

先把话说明白：这不是那种「一键搬家」的傻瓜工具，它需要你本机装好 OneNote 和 Word，但换来的是一套可控、可定制、格式还原度高的转换链路。下表可以帮你快速决策：

它的适用对象很清晰：想从 OneNote 迁往 Obsidian、Logseq、Joplin 等 Markdown 生态的用户，以及想给多年笔记做一份「开放格式备份」的人。需要提醒的是，它不支持 Windows 商店版 OneNote，且密码保护分区、手写笔迹在导出前必须自行处理。

三、环境准备：先花五分钟把运行条件配齐

工具依赖三样东西，缺一不可：

• 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。打开 OneNote，确认要导出的笔记本已加载并完成同步。同步非常重要，云上还没下载到本地的图片，导出时是抓不到的。

四、首次导出：交互模式与命令行模式任选

4.1 交互式操作（适合第一次试跑）

用 Visual Studio 或 MSBuild 编译生成OneNoteMdExporter.exe后，双击运行，按照提示走完四个步骤：

1. 按回车进入程序，此时屏幕上会列出本机所有笔记本，输入编号选择要导出的笔记本（输入0表示导出全部）。
2. 选择导出格式：1为 Markdown 文件夹格式，2为 Joplin 原始目录格式。
3. 询问是否打开高级设置时，输入yes会用记事本打开appSettings.json，想微调就在这里改；直接回车则用默认配置导出。
4. 导出完成后，程序会自动用资源管理器打开导出目录。

默认导出位置：Exports\Markdown\{笔记本名}-{时间戳}\，时间戳保证了每次导出都会生成独立文件夹，反复导出不会互相覆盖，这一点对后续迭代调参非常友好。

4.2 命令行模式（适合批量与自动化）

如果你要同时处理多个笔记本，或者想写脚本定时执行，命令行参数是更好的选择。先查看完整说明：

OneNoteMdExporter.exe --help

核心参数速查表：

一条完整的批量导出命令：

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

如果只想导出指定笔记本的某个分区，可以精确到分区和页面级别：

OneNoteMdExporter.exe --notebook "工作日志" --section "2024" --page "周报" --format 1 --no-input

命令行模式下仍会生成logs.txt日志文件，排查问题时要善用这份日志。

五、核心配置逐项拆解：改之前先明白这三件事

配置集中在程序目录下的appSettings.json。对每个参数，你都应该问自己三个问题：**它是什么、为什么这样配、不改会怎样。**下面挑影响最大的几项展开。

5.1 页面层级怎么处理

"ProcessingOfPageHierarchy": "HierarchyAsFolderTree"

• 是什么：控制 OneNote 里「父页面 → 子页面」的上下级关系如何落到文件系统。
• 三个可选值：
  • HierarchyAsFolderTree：父页面变成一个文件夹，子页面放进去，即分区/父页面/子页面.md，结构最直观。
  • HierarchyAsPageTitlePrefix：层级合并进文件名，如父页面_子页面.md，适合层级浅、希望文件平铺的场景。
  • IgnoreHierarchy：完全忽略页面层级。
• 不配会怎样：默认即文件夹树方案，对绝大多数人已是正确选择；只有当你发现嵌套过深导致路径过长，才需要改用前缀方案。

5.2 图片和附件放哪里

"ResourceFolderLocation": "RootFolder"

• 是什么：决定图片、附件等资源文件的存放位置。
• 两个可选值：
  • RootFolder：所有资源集中到一个根目录下的resources文件夹，文件引用使用相对路径，适合资源量大、想统一管理的场景。
  • PageParentFolder：资源放在各自 Markdown 文件旁边，单文件自包含，方便单独移动某个页面。
• 不配会怎样：如果你后续打算把单篇笔记分享或单独归档，集中式存储会导致图片「跟丢」；反之大量散落的小资源文件夹会让目录显得杂乱。建议迁往 Obsidian 选 RootFolder，逐篇搬运选 PageParentFolder。

5.3 内部链接怎么转换

"OneNoteLinksHandling": "ConvertToWikilink"

• 是什么：处理笔记中形如onenote://...的内部链接。
• 四个可选值：
  • KeepOriginal：原样保留 onenote:// 链接，离开 OneNote 后基本是死链。
  • ConvertToMarkdown：转为文字标准 Markdown 链接，适合 Joplin。
  • ConvertToWikilink：转为[[页面标题|显示文字]]Wiki 链接，Obsidian 用户建议选这个，双向链接直接生效。
  • Remove：删除链接但保留文字。
• 不配会怎样：默认值就是 Wikilink；如果你迁往 Joplin 却不改配置，会得到一批 Obsidian 语法风格的链接。跨笔记本链接和指向分区的链接在转换中会被移除，这是当前版本的限制。

5.4 其他值得关注的开关

六、三个实战场景：照着做就能出结果

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

需求：保留笔记间相互引用关系，让双向链接在 Obsidian 中可点击跳转。

步骤：

1. 修改appSettings.json：OneNoteLinksHandling设为ConvertToWikilink，AddFrontMatterHeader保持true。
2. 执行导出：

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

3. 在 Obsidian 中「打开文件夹作为仓库」，指向导出目录即可。

效果评估：笔记本 → 分区 → 页面层级还原为文件夹树，内部页面互链变成可点击的 Wiki 链接，Front Matter 中的时间信息可以直接用于 Dataview 类插件。

场景二：整体迁入 Joplin

需求：Joplin 有自己的原始目录格式，导入后能保留笔记本层级和页面排序。

步骤：

1. 在交互模式选择格式2（Joplin Raw Folder），或在命令行指定--format 2。
2. 将OneNoteLinksHandling改为ConvertToMarkdown，PanDocMarkdownFormat保持gfm。
3. 导出完成后，在 Joplin 中使用「导入 → 原始文件（Joplin 目录）」功能导入。

效果评估：Joplin 格式能保留分区顺序和页面顺序，这恰恰是 Markdown 文件夹格式做不到的（Markdown 格式下页面排序依赖文件名），在意页面顺序就选 Joplin 格式。

场景三：给十年笔记做一份跨平台备份

需求：不绑定任何特定软件，得到一份任何编辑器都能读的开放格式存档。

步骤：

1. 先在 OneNote 中执行「文件 → 导出 → 笔记本 → OneNote 包 (.onepkg)」，生成一份原始备份。
2. 再用工具以 Markdown 格式导出一份，双备份策略：

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

效果评估：.onepkg是 OneNote 原生格式，用于灾难恢复；Markdown 导出保证内容永远可读。两份互为补充，即使 OneNote 日后停止维护，知识资产也不会被锁死。

七、高频问题排查：报错不要慌，按清单来

问题一：启动后报System.Runtime.InteropServices.COMException

表现：程序一运行就抛 COM 异常退出。

根因：本机 OneNote/Office 组件注册异常，或工具与 OneNote 以管理员身份运行导致权限不匹配。

解决顺序：

1. 确认工具和 OneNote 都以普通权限启动（不要右键「以管理员身份运行」）。
2. 重新注册 OneNote 组件后重试。
3. 如果仍然报错，在 OneNote 中把笔记本导出为.onepkg包，在另一台正常机器上导入后再导出（详见项目 doc 目录下的notebook-onepkg-export.md）。

问题二：导出后部分图片丢失或链接损坏

表现：Markdown 文件正常，但resources里缺图，引用指向空文件。

根因：图片只存在于云端，未同步到本地。

解决：在 OneNote 中进入「文件 → 选项 → 同步」，勾选「下载所有文件和图像」，强制同步后再重新导出。导出前务必先同步，这是最容易被忽略的一步。

问题三：导出的内容比预期少

表现：某些分区或页面缺失。

排查思路：

• 密码保护的分区在解锁前不会导出，先解锁再导出。
• 手写笔迹无法转换，属于已知限制；手写页面只能靠图片方式手动处理。
• 绘图内容会被压平为图片，格式细节会丢失，属于正常现象。

问题四：导出中途中断

表现：大量页面时报错退出。

解决：加入--ignore-errors跳过出错页面，导出完成后检查logs.txt中记录的失败页面清单，再单独重试。

八、性能优化与最佳实践清单

这份清单来自实际使用经验，直接照做即可：

• 先同步再导出：导出前强制同步整个笔记本，能避免绝大多数图片丢失问题。
• 善用时间戳目录：每次导出生成独立文件夹，改配置后放心重跑，新旧版本可对比差异。
• 小步快跑调参：先用--section或--page导出单个分区验证效果，确认满意后再全量导出。
• 路径长度是隐形杀手：笔记标题很长时，把PageTitleMaxLength和MdMaxFileLength调小，避免文件系统路径超限。
• 保留logs.txt：遇到问题先看日志，报 bug 时附上日志能大幅加快定位。
• 双备份原则：迁移完成后先不要删除 OneNote 原数据，抽样检查 10% 页面确认无误再清理。
• 模板先行：涉及复杂格式（表格、颜色、折叠段落）的页面，建议先用小笔记本试导出，确认目标编辑器渲染正常。

九、接下来你可以做什么

如果你读到这里，说明已经准备好动手了。按这个顺序推进即可：

1. 克隆仓库并完成 Pandoc 解压，跑通第一次交互式导出。
2. 用一个小测试分区验证不同配置项的效果，选定你的目标平台（Obsidian 还是 Joplin）并锁定对应配置。
3. 编写批量导出命令，把正式笔记本一次性迁出，并做抽样质检。
4. 保留.onepkg原始备份，确认无误后再清理旧数据。

如果你在使用中发现问题，可以带着logs.txt和错误信息到项目的问题区反馈；想参与贡献的话，项目根目录的doc/contribute.md描述了协作规范，Resources目录下的多语言文件（含中文）也欢迎翻译改进。一次完整的迁移需要耐心，但把多年积累的知识从专有格式里解放出来，这件事值得认真做。

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