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 里，躺着五六年甚至更久的笔记：工作总结、读书笔记、项目文档、随手截图……一旦想换个工具，最大的阻力不是操作麻烦，而是"搬过去会不会全乱套"的担忧。onenote-md-exporter 正是冲着这个问题来的：一款运行在 Windows 上的开源命令行工具，能在本地直接把 OneNote 笔记本转换为 Markdown，供 Obsidian、Joplin 等平台使用，全程不经过任何云端，格式还原度在同类方案里属于第一梯队。本文不打算罗列全部参数，而是从三个最让用户纠结的问题出发，带你走完一次完整的笔记迁移流程。

问题一：搬完家，层级和格式还完整吗？

症状：用"另存为"或在线工具导出后，原本"笔记本→分区→子分区→页面→子页面"的多级结构被拍扁成一张清单；表格错位、彩色文字消失、折叠段落全部展开。

原因：OneNote 把内容存在私有格式里，普通导出手段只能捞到"看得见的文本"，结构关系和样式细节基本带不走。

解法：onenote-md-exporter 采用一条特殊的转换链路——先用 OneNote 官方接口把每个页面读出来转成 DocX，再借助 Pandoc 把 DocX 翻译成 Markdown，前后还各有一道 XML 预处理和正则后处理来修复格式。在 Markdown 格式下，分区和分区组默认导出为文件夹层级，页面层级则给你两种选择：

• HierarchyAsFolderTree（默认）：父页面成为子页面的文件夹，例如Section1/父页面/子页面.md
• HierarchyAsPageTitlePrefix：把父页面名作为子页面文件名前缀，例如Section1/父页面_子页面.md

至于内容本身能保到什么程度，项目文档里有一张支持矩阵，摘录几个关键项：

也就是说，常规内容基本都能完好带走；手写内容是目前唯一确定会丢失的类型，迁移前最好先截图留档。

问题二：笔记之间的链接，换平台还点得通吗？

症状：在 OneNote 里精心维护的互链关系，导出后全部变成onenote://开头的死链接，点一下毫无反应。

原因：OneNote 内部链接走的是私有协议，任何第三方编辑器都识别不了。

解法：设置项OneNoteLinksHandling直接决定链接的归宿，共四种策略：

需要提醒的是：无论选哪种，跨笔记本的链接和指向分区页的链接都会被移除，这是格式本身的限制，别等导出完才发现。

问题三：图片和附件，会不会丢在迁移路上？

症状：导出目录里图片缺了一大半，或者引用路径全部失效。

原因：多数时候不是工具的问题，而是 OneNote 云端根本没把图片下载到本地；另外资源文件的存放方式也会影响 Markdown 里的引用路径。

解法：两步走。第一步，打开 OneNote 的 文件→选项→同步，勾选"下载所有文件和图像"，强制同步一次再导出。第二步，用ResourceFolderLocation决定资源放哪：

• RootFolder（默认）：所有图片和附件集中到导出根目录的 resources 文件夹，适合图片多的笔记本，也方便整体拷贝
• PageParentFolder：资源放在各自 md 文件旁边，结构最直观，适合把单篇笔记单独分享的场景

第一次导出：从环境准备到出结果，不到十分钟

两步完成环境准备

1. 备齐三样软件：Windows 10 及以上、OneNote 2013 及以上（Windows 商店版不支持）、Word 2013 及以上。项目基于 .NET 10 自包含发布，通常不需要额外安装运行时。
2. 获取程序：克隆仓库后，把src/OneNoteMdExporter/pandoc/目录下的 pandoc 压缩包解开，确保pandoc.exe就位：

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

交互式导出，跟着提示走

启动OneNoteMdExporter.exe，它会依次问你：选哪个笔记本（输 0 可全部导出）、选哪种格式（1 是 Markdown，2 是 Joplin）、要不要顺手改一下高级配置。确认后导出开始，这段时间你可以去冲杯咖啡 ☕，结束后程序会自动打开导出文件夹。

命令行方式，适合批量与自动化

交互之外，程序支持完整的命令行参数，跑一次--help就能全部掌握。常用的几个：

# 导出指定笔记本为 Markdown（格式 1） OneNoteMdExporter.exe --notebook "工作笔记" --format 1 # 导出全部笔记本，不等待任何输入 OneNoteMdExporter.exe --all-notebooks --no-input # 只导出某个分区下的某个页面 OneNoteMdExporter.exe --notebook "工作笔记" --section "项目A" --page "需求文档"

配合--ignore-errors，可以在个别页面出错时继续导出剩余内容，适合无人值守跑批。

真实场景：1200 篇技术笔记搬进 Obsidian

一位后端工程师的笔记本里有 1200 篇技术笔记，目标是整体迁入 Obsidian。他的做法是：

1. 保持默认的HierarchyAsFolderTree，让"笔记本→分区→子页面"的层级原样落地成文件夹
2. 开启AddFrontMatterHeader，让每篇笔记带上前言元数据（标题、创建与修改时间），方便按日期检索
3. 链接策略选ConvertToWikilink，笔记间的互链直接变成 Obsidian 双链，反向链接面板立刻可用
4. PanDocMarkdownFormat保持gfm，语法与 Obsidian 完全兼容

导出后按三件事验收：文件夹层级是否与原笔记本一一对应、随机抽 10% 的页面核对表格与图片、再随便点开几条双链确认跳转正常。整个迁移都在本地完成，没有任何内容经过网络，这在处理含客户信息的笔记时格外重要。

结合你的目标软件，把配置调到最佳

不同平台的"脾气"不一样，这里给三套经过验证的组合：

其他几个值得认识的参数：PageTitleMaxLength和MdMaxFileLength控制文件名长度上限，遇到路径过长报错时把它们调小即可；IndentingStyle决定 OneNote 的缩进在 Markdown 里如何呈现，默认保持原样，也可以转成项目符号列表。

三个常见的坑，帮你提前避开

坑一：启动即报 COMException。这类错误通常是本机 Office 安装异常导致的。可以先尝试重装 Office；更省事的办法是把笔记本导出为 .onepkg 文件（见项目里的 doc/notebook-onepkg-export.md），换一台干净的电脑导入后再导出。

坑二：导出后图片缺失。回到前面的问题三，先确认 OneNote 已开启"下载所有文件和图像"并强制同步，再重跑一遍导出。

坑三：文件名带特殊字符导致路径错误。用命令行时记得给笔记本名加引号；如果报路径过长，把MdMaxFileLength从 50 往下调。

另外，项目以 GPL v3 协议发布，作者明确声明导出过程中存在丢失数据的可能，动手前务必给 OneNote 笔记留一份备份——这比任何配置都重要。

给迁移留个稳妥的节奏

知识迁移不该是"一天搬完"的豪赌，而是一次可以分步验证的过程。建议先用仓库里的sample/TestNotebook.onepkg试跑一遍，把配置和流程跑通，再挑一个你最看重的笔记本正式导出，确认效果后逐步扩大范围。如果你用下来发现问题，或者想帮忙完善多语言翻译（中文本地化文件就在src/OneNoteMdExporter/Resources/目录下），项目的 doc/contribute.md 写清了贡献方式。从第一本笔记本开始，你的知识资产就离"可检索、可迁移、不过期"的 Markdown 更近一步了。

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