一篇搞定 OneNote 笔记迁移：onenote-md-exporter 完整使用指南

一篇搞定 OneNote 笔记迁移：onenote-md-exporter 完整使用指南

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

你是不是也有这样一天：攒了七八年的 OneNote 笔记本里躺着上千条笔记，从读书摘抄到项目复盘，从会议记录到技术备忘，全都锁在一个日渐臃肿的 .one 文件里。想换到 Obsidian 或者 Joplin，却发现官方导出只给你一份网页存档，层级关系全乱、表格变形、内部链接全部失效，更别提那些需要把私人笔记上传到云端才能转换的在线工具——想想就劝退。

onenote-md-exporter 就是为解决这件事而生的。它是一个运行在 Windows 上的本地命令行工具，能把 OneNote 笔记本完整地导出为 Markdown 格式，保留分区层级、页面结构、图片附件和内部链接，数据全程不出你的电脑。本文会从零开始，带你完成第一次导出，再演示两个真实迁移场景，最后把常见报错和配置陷阱一次性讲清楚。

它到底能帮你保住什么

先别急着动手，花一分钟看看这个工具的"能力清单"，确认它是不是你要找的那个：

• 结构不塌方：笔记本 → 分区 → 子分区 → 页面，导出后是规整的文件夹树，而不是一堆扁平化的 md 文件；
• 图片附件不丢：页内图片和文件附件会原样复制出来，并自动在 Markdown 里生成正确引用；
• 表格分两档处理：简单表格转成标准 Markdown 表格，复杂表格（比如带合并单元格的）保留为 HTML，前提是你的编辑器支持 HTML 渲染；
• 内部链接可转换：OneNote 的 onenote:// 链接可以转成 Obsidian 风格的 Wiki 链接或标准 Markdown 链接；
• 元数据可保留：每页开头能自动生成包含标题、创建时间、修改时间的 YAML Front Matter；
• 文本标签变表情：任务、星标等标签会转成对应 emoji，不至于彻底消失；
• 完全离线：不需要把笔记上传到任何服务器。

也有几个诚实的边界：手写笔迹会丢失，密码保护分区不提前解锁就导不出来，绘图内容会被扁平化成图片。这些在动手前知道，比事后发现强得多。

从零到第一次导出，四步走

第 1 步：核对环境

这个工具依赖 Windows 上的 Office 组件，所以需要满足：

• Windows 10 或更高版本；
• OneNote 2013 及以上版本——注意，Windows 商店版"OneNote for Windows"不支持；
• Word 2013 及以上版本（它负责把页面内容转成 DocX，再交给 Pandoc 变成 Markdown）。

提前打开 OneNote，确认要导出的笔记本已经加载、同步完成。这一步很重要，工具是实时读取 OneNote 当前打开状态的。

第 2 步：准备工具本体

从项目仓库克隆或下载最新发布包：

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

解压后找到pandoc目录，里面有个压缩包pandoc-3.8.3-windows-x86_64.zip，必须把里面的pandoc.exe解压出来放到同一目录下，否则程序启动时会直接报错——这是新手最常见的第一个坑。

第 3 步：以图形交互方式跑通一遍

直接双击运行OneNoteMdExporter.exe，程序会：

1. 列出 OneNote 里检测到的所有笔记本，输入编号回车（输入 0 表示导出全部）；
2. 让你选导出格式：1是 Markdown，2是 Joplin Raw Folder；
3. 问你是否要修改高级设置——第一次先用默认设置直接导出即可；
4. 显示"开始导出"，去喝杯咖啡，导出完成后会自动用资源管理器打开导出目录。

默认导出位置在程序同级的Exports\目录下。如果你想命令行一步到位，可以这样写：

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

第 4 步：看懂导出的成果

一个典型导出结果长这样：

技术笔记/ ├── 读书笔记/ │ ├── 2024年书单.md │ └── 阅读方法总结.md ├── 项目复盘/ │ ├── 需求文档/ │ │ ├── 一期需求.md │ │ └── 二期规划.md │ └── 复盘模板.md └── resources/ ├── image1.png └── 附件.pdf

每个页面是一个.md文件，子页面会自动生成对应的子文件夹；图片和附件统一收进resources文件夹，Markdown 里的引用路径是相对路径，整个文件夹拷到哪都能正常显示。

两个实战场景：Obsidian 与 Joplin 迁移

场景一：把笔记库搬进 Obsidian

Obsidian 是纯本地 Markdown 笔记应用，和这个工具简直是天作之合。迁移前，建议先改两个配置：

打开程序目录下的appSettings.json，把OneNoteLinksHandling设为ConvertToWikilink，这样 OneNote 内部链接会变成[[页面标题|显示文字]]形式的双链，Obsidian 能直接识别。同时确认ProcessingOfPageHierarchy保持默认的HierarchyAsFolderTree，父页面作为子页面的文件夹，这样层级关系最直观。

然后执行：

OneNoteMdExporter.exe --notebook "我的知识库" --format 1

导出完成后，用 Obsidian "打开本地仓库"选择导出目录即可。Obsidian 支持 HTML 渲染，所以复杂表格、字体颜色这些用 HTML 保存的格式都能正常显示。

场景二：整库迁往 Joplin

Joplin 用户有专属待遇：导出格式选2，工具会生成 Joplin 官方的原始目录格式，直接导入，比传统的"OneNote → ENEX → Joplin"方案强得多——后者会把分区层级压平成标签、把页面顺序打乱。

操作流程：

OneNoteMdExporter.exe --notebook "会议记录" --format 2

记下导出目录路径，打开 Joplin，依次点击 文件 → 导入 → "RAW - Joplin Export Directory"，选择该目录即可。Joplin 的分区层级、页面顺序、笔记内嵌图片都会被完整还原，附件引用用的是 Joplin 的:/资源ID语法，导入后自动生效。

如果你只想导出一小部分，命令行还支持按分区和页面过滤：

OneNoteMdExporter.exe --notebook "项目文档" --section "2025年" --page "周报模板" --format 1

配合--no-input参数可以完全无人值守，适合写进批处理脚本定时执行。

高频疑问速查

Q：启动时报 COMException 错误怎么办？通常是本机 Office 安装有问题。建议先彻底卸载重装 Office；另一个稳妥方案是把你自己的笔记本导出为 .onepkg 包（OneNote 里 文件 → 导出 → 笔记本 → OneNote 包），在另一台正常电脑上导入后再运行工具导出。

Q：导出后发现部分图片丢失或损坏？多半是 OneNote 本地没有缓存全量图片。到 OneNote 的 文件 → 选项 → 同步 里勾选"下载所有文件和图像"，强制同步后重新导出即可。

Q：文件名太长导致导出失败？页面和分区名会用作文件名，超长标题会触发 Windows 路径长度限制。在appSettings.json里调低MdMaxFileLength（默认 50）就能缓解。

Q：希望每页都有创建/修改时间？AddFrontMatterHeader默认就是true，每页顶部会自动生成 YAML 头：

--- title: 页面标题 updated: 2021-11-11 14:55:00Z created: 2021-11-11 14:54:43Z ---

Q：导出的 Markdown 在编辑器里排版乱了？如果你用的编辑器不支持 HTML（比如某些极简编辑器），把UseHtmlStyling改成false，程序会放弃用 HTML 保存样式，改用更朴素的格式。

背后的转换原理：一个"翻译官"的流水线

不深入源码，用一个比喻就能说清它的工作方式。你可以把 OneNote 想象成一座装修风格很独特的房子，Markdown 是另一套截然不同的装修标准。直接搬家具肯定摔碎东西，所以这个工具的做法是：

1. 通过 OneNote 官方 COM 接口，把整座房子的结构（分区、页面层级）和每件家具（段落、图片、表格）读出来；
2. 先做一次"预清洗"，把 OneNote 页面 XML 里不规范的折叠段落、背景色、字体颜色整理好；
3. 让 Word 把页面导出成 DocX 中间格式——这是 Pandoc 最擅长的输入；
4. Pandoc 这个"万能翻译官"把 DocX 转成 Markdown；
5. 最后再用一套正则规则做"质检修补"，修正换行过多、误生成的引用块、多余页眉等小毛病。

整个过程在本地完成，中间产物是临时 DocX 文件，导出结束后会自动清理。这也是为什么它比 OneNote 自带的"另存为 Markdown"（几乎不存在）和第三方在线转换器都更可靠的原因——每个环节都用最成熟的开源工具，再针对 OneNote 的怪癖做定向修复。

避坑清单与建议

• 导出前先同步：确保 OneNote 全部同步完成，否则容易丢最新内容；
• 先小后大：用 sample 目录里的测试笔记本TestNotebook.onepkg或者新建一个几页的小笔记本先试跑，摸清配置效果再动真格的；
• 备份是底线：工具本身也提醒你，导出结果可能有意外丢失，正式迁移前务必给 OneNote 做一次 .onepkg 备份；
• 按内容选资源策略：图片多的笔记本用默认的RootFolder（资源集中存放）更清爽，链接多的笔记本优先ConvertToWikilink；
• 缩进内容别忽略：如果笔记里大量使用缩进排版，试试把IndentingStyle从默认值改为ConvertToBullets，缩进会变成项目符号，观感最好；
• 善用日志：程序同级目录会生成logs.txt，报错时翻一翻，信息比弹窗详细得多。

现在，开始你的迁移

OneNote 并不是不好，只是当你想要本地文件、纯文本、可版本管理、能被任意编辑器打开的笔记时，它就显得封闭了。onenote-md-exporter 给了你一条成本最低的出路：不依赖云、不需要付费、转换质量经得起抽查。从一本最常用的笔记本开始，导出来放到 Obsidian 或 Joplin 里体验一两天，再决定要不要把整个知识库都搬过去。

如果你在导出过程中遇到新问题，或者想支持更多语言和导出格式，欢迎参与项目贡献：报告 bug、补充翻译、提交测试样例都可以。迁移这件事，一个人搬很累，大家一起把工具打磨好，每个人都能省下大把时间。

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