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-md-exporterOneNote 自带导出在线转换工具数据处理位置完全本地数据不出机本地上传云端有泄露风险分区层级结构完整还原为文件夹树基本丢失大多扁平化内部链接可转 Wiki 链接 / Markdown 链接保留为 onenote:// 死链多数直接丢弃复杂表格转为 Markdown 表格或 HTML 表格样式丢失还原度不稳定页面层级父页/子页文件夹树或标题前缀两种策略不支持不支持批量与无人值守完整命令行参数支持不支持视平台而定可定制性appSettings.json 十余项配置无无它的适用对象很清晰想从 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后双击运行按照提示走完四个步骤按回车进入程序此时屏幕上会列出本机所有笔记本输入编号选择要导出的笔记本输入0表示导出全部。选择导出格式1为 Markdown 文件夹格式2为 Joplin 原始目录格式。询问是否打开高级设置时输入yes会用记事本打开appSettings.json想微调就在这里改直接回车则用默认配置导出。导出完成后程序会自动用资源管理器打开导出目录。默认导出位置Exports\Markdown\{笔记本名}-{时间戳}\时间戳保证了每次导出都会生成独立文件夹反复导出不会互相覆盖这一点对后续迭代调参非常友好。4.2 命令行模式适合批量与自动化如果你要同时处理多个笔记本或者想写脚本定时执行命令行参数是更好的选择。先查看完整说明OneNoteMdExporter.exe --help核心参数速查表参数作用示例-n, --notebook指定笔记本名称--notebook 技术笔记-f, --format导出格式1Markdown2Joplin--format 1-s, --section只导出指定分区--section Python 笔记-p, --page只导出指定页面--page 入门教程--all-notebooks导出全部笔记本单独使用即可--no-input跳过所有交互提示实现无人值守配合脚本使用--ignore-errors单页出错时跳过继续而非中断大批量导出时建议加上一条完整的批量导出命令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 其他值得关注的开关配置默认值一句话说明AddFrontMatterHeadertrue每页开头加 YAML 元数据标题、创建/更新时间Obsidian 检索和排序会用到PanDocMarkdownFormatgfm输出语法风格GitHub 风格兼容性最好UseHtmlStylingtrue用 HTML 保留字体颜色、背景色等样式前提是你的编辑器支持 HTMLIndentingStyleLeaveAsIs处理缩进留空、转全角空格或转列表ResourceFolderNameresources资源文件夹名称可按需改名PageTitleMaxLength50页面标题超长时自动截断防止文件路径过长报错MdMaxFileLength50文件/文件夹名长度上限路径超限时调小六、三个实战场景照着做就能出结果场景一把 1000 篇技术笔记迁入 Obsidian需求保留笔记间相互引用关系让双向链接在 Obsidian 中可点击跳转。步骤修改appSettings.jsonOneNoteLinksHandling设为ConvertToWikilinkAddFrontMatterHeader保持true。执行导出OneNoteMdExporter.exe --notebook 技术笔记 --format 1 --no-input在 Obsidian 中「打开文件夹作为仓库」指向导出目录即可。效果评估笔记本 → 分区 → 页面层级还原为文件夹树内部页面互链变成可点击的 Wiki 链接Front Matter 中的时间信息可以直接用于 Dataview 类插件。场景二整体迁入 Joplin需求Joplin 有自己的原始目录格式导入后能保留笔记本层级和页面排序。步骤在交互模式选择格式2Joplin Raw Folder或在命令行指定--format 2。将OneNoteLinksHandling改为ConvertToMarkdownPanDocMarkdownFormat保持gfm。导出完成后在 Joplin 中使用「导入 → 原始文件Joplin 目录」功能导入。效果评估Joplin 格式能保留分区顺序和页面顺序这恰恰是 Markdown 文件夹格式做不到的Markdown 格式下页面排序依赖文件名在意页面顺序就选 Joplin 格式。场景三给十年笔记做一份跨平台备份需求不绑定任何特定软件得到一份任何编辑器都能读的开放格式存档。步骤先在 OneNote 中执行「文件 → 导出 → 笔记本 → OneNote 包 (.onepkg)」生成一份原始备份。再用工具以 Markdown 格式导出一份双备份策略OneNoteMdExporter.exe --all-notebooks --format 1 --no-input --ignore-errors效果评估.onepkg是 OneNote 原生格式用于灾难恢复Markdown 导出保证内容永远可读。两份互为补充即使 OneNote 日后停止维护知识资产也不会被锁死。七、高频问题排查报错不要慌按清单来问题一启动后报System.Runtime.InteropServices.COMException表现程序一运行就抛 COM 异常退出。根因本机 OneNote/Office 组件注册异常或工具与 OneNote 以管理员身份运行导致权限不匹配。解决顺序确认工具和 OneNote 都以普通权限启动不要右键「以管理员身份运行」。重新注册 OneNote 组件后重试。如果仍然报错在 OneNote 中把笔记本导出为.onepkg包在另一台正常机器上导入后再导出详见项目 doc 目录下的notebook-onepkg-export.md。问题二导出后部分图片丢失或链接损坏表现Markdown 文件正常但resources里缺图引用指向空文件。根因图片只存在于云端未同步到本地。解决在 OneNote 中进入「文件 → 选项 → 同步」勾选「下载所有文件和图像」强制同步后再重新导出。导出前务必先同步这是最容易被忽略的一步。问题三导出的内容比预期少表现某些分区或页面缺失。排查思路密码保护的分区在解锁前不会导出先解锁再导出。手写笔迹无法转换属于已知限制手写页面只能靠图片方式手动处理。绘图内容会被压平为图片格式细节会丢失属于正常现象。问题四导出中途中断表现大量页面时报错退出。解决加入--ignore-errors跳过出错页面导出完成后检查logs.txt中记录的失败页面清单再单独重试。八、性能优化与最佳实践清单这份清单来自实际使用经验直接照做即可先同步再导出导出前强制同步整个笔记本能避免绝大多数图片丢失问题。善用时间戳目录每次导出生成独立文件夹改配置后放心重跑新旧版本可对比差异。小步快跑调参先用--section或--page导出单个分区验证效果确认满意后再全量导出。路径长度是隐形杀手笔记标题很长时把PageTitleMaxLength和MdMaxFileLength调小避免文件系统路径超限。保留logs.txt遇到问题先看日志报 bug 时附上日志能大幅加快定位。双备份原则迁移完成后先不要删除 OneNote 原数据抽样检查 10% 页面确认无误再清理。模板先行涉及复杂格式表格、颜色、折叠段落的页面建议先用小笔记本试导出确认目标编辑器渲染正常。九、接下来你可以做什么如果你读到这里说明已经准备好动手了。按这个顺序推进即可克隆仓库并完成 Pandoc 解压跑通第一次交互式导出。用一个小测试分区验证不同配置项的效果选定你的目标平台Obsidian 还是 Joplin并锁定对应配置。编写批量导出命令把正式笔记本一次性迁出并做抽样质检。保留.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考