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-md-exporter 这款免费开源工具展开，教你如何把 OneNote 笔记本完整、无损地转换为 Markdown 文件，解决笔记迁移中的格式丢失、层级扁平化与链接失效三大痛点。无论你的目标是切换到 Obsidian、Joplin，还是给多年笔记做一份开放格式的长期备份，这篇文章都会给你一份从安装、配置到自动化的完整路线图。

一个周末下午的真实困境

小陈是某科技公司的产品经理，四年来的会议纪要、需求文档、用户访谈全躺在 OneNote 里，累计 2000 多个页面。公司决定全面切换笔记平台，他试着把内容复制粘贴到新工具里——结果表格全乱、图片位置丢失、几十条页面互相引用的内部链接全部变成死链。最要命的是，OneNote 精心整理的分区层级，在导出后全部被"拍扁"成平铺文件。

他的经历并非个例。OneNote 用户迁移时普遍面临三类问题：复杂格式还原度低、页面层级结构被摊平、笔记间的关联链接全部失效。手动复制黏贴不现实，在线转换服务又要把私人笔记上传到云端，数据安全没有保障。如果你也在为类似的事情发愁，onenote-md-exporter 就是为你准备的答案。

这个工具到底是什么

onenote-md-exporter 是一个运行在 Windows 上的命令行程序，作用只有一个：把 OneNote 笔记本批量导出为 Markdown 格式。它有两个特点让它和其他导出方式区分开来：

• 完整保留结构：分区、分区组、页面父子关系都会按照你的选择还原成文件夹树或文件名前缀。
• 完全离线运行：所有处理都在本机完成，不依赖微软云端，也不会上传任何数据。

它适合三类人：正在评估或迁移到 Obsidian、Joplin 等 Markdown 笔记软件的用户；想把 OneNote 数据转成开放格式长期归档的用户；需要把企业 OneNote 文档整体转移到 Markdown 协作平台的团队。

底层是怎么工作的

整个导出过程可以看作一条流水线，源码中对应的核心类位于src/OneNoteMdExporter/Services/Export/：

1. 数据提取：通过 OneNote 与 Word 的官方 Interop API，把每个页面发布成 DocX 临时文件，同时读取页面 XML 结构。
2. 格式转换：调用内置的 Pandoc 引擎，把 DocX 翻译成目标 Markdown 语法（默认 GitHub Flavored Markdown）。
3. 后处理修复：对生成的 Markdown 做多轮正则修正，包括去重复空行、清理多余引用块、把 HTML 图片标签转成标准 Markdown 引用等。

值得一提的是，在转换之前工具还会对页面 XML 做预处理，比如展开折叠段落、把 OneNote 标签转成对应的表情符号、处理缩进样式。这部分逻辑在ExportServiceBase.cs的PageXmlPreProcessing方法中，如果你对实现细节感兴趣可以直接翻阅源码。

运行前的环境准备

在动手之前，先对照下面的清单检查你的电脑：

项目	要求
操作系统	Windows 10 或更高版本
OneNote	2013 及以上桌面版（商店版不支持）
Word	2013 及以上版本
运行时	无需额外安装（程序已自带 .NET 运行时）

这里有个容易踩的坑：Windows 商店里安装的 OneNote UWP 版无法被 Interop API 访问，必须使用桌面版 OneNote。如果你不确定自己装的是哪个版本，可以先打开 OneNote，在"文件 > 账户"里查看版本信息。

三步完成安装

1. 获取源码：git clone https://gitcode.com/gh_mirrors/on/onenote-md-exporter
2. 打开src/OneNoteMdExporter/pandoc/目录，把里面的pandoc-3.8.3-windows-x86_64.zip解压，将pandoc.exe放到该目录下。
3. 用 Visual Studio 打开src/OneNoteMdExporter.sln编译，或直接使用发布版程序。

如果你只是想快速试用而不关心源码，直接运行编译好的OneNoteMdExporter.exe即可。仓库里还附带了一个sample/TestNotebook.onepkg示例笔记本，可以先拿它练手，不用拿自己的正式笔记冒险。

第一次运行：全程交互式操作

启动前记得先打开 OneNote 并确保要导出的笔记本已完成同步。接着双击运行程序，按下面的提示一步步走：

1. 程序会列出检测到的笔记本，输入序号选择要导出的那一个；输入0表示导出全部笔记本。
2. 选择导出格式：输入1导出为标准 Markdown 文件夹，输入2导出为 Joplin Raw Directory 格式。
3. 程序询问是否调整设置时，输入y会用记事本打开appSettings.json，你可以顺手改几项（下文会讲怎么改）。
4. 确认后进入两阶段处理：先扫描构建页面树，再逐页导出转换。期间你可以安心去冲杯咖啡 ☕。
5. 全部完成后，程序会自动用资源管理器打开导出文件夹，检查结果即可。

首次运行时如果遇到System.Runtime.InteropServices.COMException之类的报错，多半是 OneNote 没有完全启动或 Office 安装有问题，可以先重启 OneNote 再试。完整的排查思路放在后文的 FAQ 里。

命令行模式：参数化批量导出

交互式操作适合第一次试用，真正的高效玩法是命令行参数。运行OneNoteMdExporter.exe --help可以查看全部参数说明：

参数	说明
-n, --notebook	指定要导出的笔记本名称
-f, --format	导出格式：1为 Markdown，2为 Joplin 文件夹
-s, --section	只导出指定分区（需配合--notebook）
-p, --page	只导出指定页面（需配合--section）
--all-notebooks	导出所有笔记本
--no-input	全程无需人工输入，适合脚本调用
--debug	调试模式，保留临时文件并输出详细日志
--ignore-errors	某页导出失败时跳过继续，不中断整个任务

几个实用示例：

# 导出"工作笔记"笔记本为 Markdown，输出到指定目录 OneNoteMdExporter.exe --notebook "工作笔记" --format 1 --output "D:\笔记备份" # 只导出"学习资料"中"考研"分区的页面，使用 Joplin 格式 OneNoteMdExporter.exe --notebook "学习资料" --format 2 --section "考研" # 静默导出全部笔记本，适合放入计划任务 OneNoteMdExporter.exe --all-notebooks --no-input --ignore-errors

注意--output参数并非真实存在的选项，导出目录由程序根据笔记本名称和时间自动创建。如果对参数有疑问，建议先不加参数运行一次，观察程序实际生成的目录结构。

配置文件详解：三大核心决策

appSettings.json是决定导出效果的枢纽文件，全部配置项带注释，结构清晰。其中最重要的决策有三个。

决策一：页面层级怎么还原

OneNote 允许页面下嵌套子页面，导出时有三种处理方式（对应ProcessingOfPageHierarchy）：

取值	目录形态	适合场景
HierarchyAsFolderTree	分区/父页面/子页面.md	Obsidian 等支持文件夹嵌套的编辑器
HierarchyAsPageTitlePrefix	分区/父页面_子页面.md	偏好扁平目录、文件名自带层级
IgnoreHierarchy	分区/子页面.md	完全不需要层级信息

决策二：图片和附件放哪里

ResourceFolderLocation决定资源文件（图片、附件）的存放位置：

• RootFolder：全部收进导出根目录下的一个统一资源文件夹，便于集中备份。
• PageParentFolder：资源放在每个页面文件旁边，方便把单页连同资源一起移动和分享。

决策三：内部链接怎么处理

OneNote 页面间的onenote://链接在导出后默认无法点击，OneNoteLinksHandling提供四种策略：

取值	转换结果	推荐平台
KeepOriginal	保留原始onenote://链接	未来可能回迁 OneNote
ConvertToMarkdown	文本	Joplin 及通用 Markdown 编辑器
ConvertToWikilink	[[页面路径\|显示文本]]	Obsidian、Logseq 等双链笔记
Remove	删除链接、仅保留显示文本	只需要干净正文

注意：跨笔记本的链接以及指向分区的链接无法转换，会被直接移除，这是当前版本的设计限制。

除了三大决策，还有几个值得留意的开关：AddFrontMatterHeader会在每个页面头部加上 YAML 元数据（标题、创建时间、更新时间），格式如下：

--- title: 页面标题 updated: 2024-05-01T10:30:00 created: 2023-11-11T09:00:00 ---

PanDocMarkdownFormat可以切换 Pandoc 支持的多种 Markdown 方言，默认gfm（GitHub 风格）兼容性最好；UseHtmlStyling决定是否保留字体颜色、背景色等 HTML 样式标签；IndentingStyle控制缩进内容的呈现方式（原样保留、转全角空格、转项目符号）。

内容保真度：哪些保留、哪些丢失

动手迁移前，最好先了解工具对各种内容类型的支持情况，避免期望落差。官方 README 里的这份对照表很有参考价值：

内容类型	支持程度	转换结果
文件附件	✅	原样复制到资源文件夹
图片	✅	提取为独立文件并插入引用
简单表格	✅	标准 Markdown 表格
复杂表格（含嵌套）	✅	HTML 表格（需编辑器支持 HTML）
折叠段落	✅	自动展开
字体颜色 / 背景色	✅	HTML 样式标签
文本标签（任务、星标等）	✅	转为对应表情符号
绘图内容	🟠	扁平化为图片
密码保护分区	🟠	导出前未解锁则丢失
手写笔记	🔴	不支持，会丢失

如果目标编辑器支持 HTML（如 Obsidian、Joplin），复杂表格和颜色样式都能保留；如果只能用纯 Markdown 渲染器，建议导出前关闭UseHtmlStyling。

再对比一下两种导出格式的差异：

特性	Markdown 格式	Joplin Raw 格式
分区层级	文件夹树	嵌套笔记本结构
分区内页面顺序	依赖文件名排序	完整保留原始顺序
页面父子层级	文件夹或文件名前缀	完整保留
内部链接	四种策略可选	转为 Joplin 资源引用
导入方式	直接使用	Joplin 菜单导入

两种格式的通用处理逻辑都封装在ExportServiceBase.cs中，差异部分分别实现在MdExportService.cs和JoplinExportService.cs，想深入了解可以对照阅读。

三个场景的推荐配置方案

下面给出三套开箱即用的配置，按你的目标平台选择。

方案 A：Obsidian 双链笔记（重点是 wikilink 和文件随页面移动）

{ "ProcessingOfPageHierarchy": "HierarchyAsFolderTree", "ResourceFolderLocation": "PageParentFolder", "OneNoteLinksHandling": "ConvertToWikilink", "AddFrontMatterHeader": true, "PanDocMarkdownFormat": "gfm+raw_html", "UseHtmlStyling": true }

方案 B：Joplin 原生导入（重点是 Markdown 链接和根目录资源）

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

Joplin 的导入步骤很简单：先以格式 2 导出，然后在 Joplin 里点击"文件 > 导入 > RAW - Joplin Export Directory"，选择导出文件夹即可。更详细的对比说明可以参考项目文档doc/migration-to-joplin.md，其中还对比了传统 OneNote→ENEX→Joplin 路线（那条路线会把分区层级拍平成标签，页面顺序也会丢失）。

方案 C：最小化通用导出

{ "ProcessingOfPageHierarchy": "IgnoreHierarchy", "ResourceFolderLocation": "RootFolder", "OneNoteLinksHandling": "Remove", "AddFrontMatterHeader": false, "PanDocMarkdownFormat": "commonmark", "UseHtmlStyling": false }

这套配置适合把笔记转成最朴素的 Markdown 做纯文本归档，任何编辑器都能正常打开。

常见问题速查

Q1：启动就报 COMException 错误，怎么办？

这通常是本机 Office 环境的问题，按顺序尝试：重启 OneNote 并登录账号 → 以管理员身份运行程序 → 修复或重装 Office。如果还不行，可以在 OneNote 里通过"文件 > 导出"把笔记本打包成.onepkg（步骤见doc/notebook-onepkg-export.md），换一台电脑导入后再导出。

Q2：导出后发现部分图片丢失或损坏？

先在 OneNote 的"文件 > 选项 > 同步"中开启"下载所有文件和图像"，强制同步笔记本后重新导出。Markdown 里引用的是相对路径，注意不要单独移动.md文件而丢下资源文件夹。

Q3：大笔记本导出很慢，怎么加速？

按分区分页分批导出（用--section、--page参数），或者配合--debug先小范围试跑；把导出目录放到 SSD 上也能明显改善 IO 性能。

Q4：能不能批量导出多个笔记本？

可以。用--all-notebooks一次导出全部，或者用 PowerShell 循环调用，见下一节。

把导出流程接入你的日常工作流

对于"每月备份一次笔记"这类重复需求，可以写一个简单的 PowerShell 脚本：

$notebooks = @("工作笔记", "项目文档", "学习资料") $exe = "C:\Tools\OneNoteMdExporter.exe" foreach ($name in $notebooks) { Write-Host "开始导出: $name" & $exe --notebook $name --format 1 --no-input --ignore-errors # 统计本次导出生成的 md 文件数量 $count = (Get-ChildItem "$env:USERPROFILE\Documents\OneNoteMdExporter" -Recurse -Filter "*.md" | Measure-Object).Count Write-Host "完成: 共 $count 个 Markdown 文件" }

再把这个脚本挂到 Windows 任务计划程序里，就能实现定时自动备份。团队场景下，也可以把导出脚本作为 CI 流程的一步，每次文档变更后自动生成最新快照，配合 Git 做版本管理。

迁移后的几件收尾小事

导出完成不等于迁移结束，建议花几分钟做这几件事：

1. 抽查渲染效果：用目标编辑器打开若干页面，确认表格、图片、链接正常。
2. 修复残余链接：用正则批量查找未转换的onenote://链接并手工处理。
3. 补充元数据：利用 Front Matter 里的创建/更新时间，在目标平台重建时间线。
4. 保留原始备份：导出前先给 OneNote 笔记本做一次备份，迁移确认无误后再清理。

现在就开始你的迁移

onenote-md-exporter 最打动人的地方在于：它把"迁移"这件事从一场噩梦变成了一个可重复执行的任务。结构完整保留、链接策略可选、全流程离线，再加上命令行和配置文件带来的自动化潜力，它完全有资格成为你笔记体系升级的起点。

不必追求一次完美，先拿示例笔记本sample/TestNotebook.onepkg或一个小分区试跑，熟悉配置项的效果，再逐步迁移正式内容。挑一个周末的下午，导出第一份 Markdown 笔记，你会发现——原来告别 OneNote 也可以这么轻松。迁移不只是搬数据，更是换一种更开放、更可控的知识管理方式，而这一步，现在就可以迈出去。

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