一篇搞定 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程序会列出 OneNote 里检测到的所有笔记本输入编号回车输入 0 表示导出全部让你选导出格式1是 Markdown2是 Joplin Raw Folder问你是否要修改高级设置——第一次先用默认设置直接导出即可显示开始导出去喝杯咖啡导出完成后会自动用资源管理器打开导出目录。默认导出位置在程序同级的Exports\目录下。如果你想命令行一步到位可以这样写OneNoteMdExporter.exe --notebook 技术笔记 --format 1第 4 步看懂导出的成果一个典型导出结果长这样技术笔记/ ├── 读书笔记/ │ ├── 2024年书单.md │ └── 阅读方法总结.md ├── 项目复盘/ │ ├── 需求文档/ │ │ ├── 一期需求.md │ │ └── 二期规划.md │ └── 复盘模板.md └── resources/ ├── image1.png └── 附件.pdf每个页面是一个.md文件子页面会自动生成对应的子文件夹图片和附件统一收进resources文件夹Markdown 里的引用路径是相对路径整个文件夹拷到哪都能正常显示。两个实战场景Obsidian 与 Joplin 迁移场景一把笔记库搬进 ObsidianObsidian 是纯本地 Markdown 笔记应用和这个工具简直是天作之合。迁移前建议先改两个配置打开程序目录下的appSettings.json把OneNoteLinksHandling设为ConvertToWikilink这样 OneNote 内部链接会变成[[页面标题|显示文字]]形式的双链Obsidian 能直接识别。同时确认ProcessingOfPageHierarchy保持默认的HierarchyAsFolderTree父页面作为子页面的文件夹这样层级关系最直观。然后执行OneNoteMdExporter.exe --notebook 我的知识库 --format 1导出完成后用 Obsidian 打开本地仓库选择导出目录即可。Obsidian 支持 HTML 渲染所以复杂表格、字体颜色这些用 HTML 保存的格式都能正常显示。场景二整库迁往 JoplinJoplin 用户有专属待遇导出格式选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 是另一套截然不同的装修标准。直接搬家具肯定摔碎东西所以这个工具的做法是通过 OneNote 官方 COM 接口把整座房子的结构分区、页面层级和每件家具段落、图片、表格读出来先做一次预清洗把 OneNote 页面 XML 里不规范的折叠段落、背景色、字体颜色整理好让 Word 把页面导出成 DocX 中间格式——这是 Pandoc 最擅长的输入Pandoc 这个万能翻译官把 DocX 转成 Markdown最后再用一套正则规则做质检修补修正换行过多、误生成的引用块、多余页眉等小毛病。整个过程在本地完成中间产物是临时 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考