OneNote笔记迁移实战用onenote-md-exporter把多年积累搬进Obsidian与Joplin【免费下载链接】onenote-md-exporterConsoleApp to export OneNote notebooks to Markdown formats项目地址: https://gitcode.com/gh_mirrors/on/onenote-md-exporteronenote-md-exporter 是一款运行在 Windows 上的命令行导出工具核心用途是把 OneNote 笔记本整体转换为 Markdown 格式让你能迁往 Obsidian、Joplin 等任何支持 Markdown 的笔记平台。本文从一个真实的使用场景出发带你完整走一遍动手准备—功能配置—整本迁移—问题排查—场景延展的全过程读完即可上手操作。一、那个想把笔记搬出 OneNote 的下午先讲一段我自己的经历。某天我打开 OneNote看着那个承载了五年工作笔记的产品资料库——里面有一百多个分区、两千多页内容包括调研纪要、会议记录、需求文档、截图和附件。我意识到自己需要换一个更开放、更好检索的笔记平台。可问题来了这些内容怎么搬出去我试过复制粘贴。结果两千页内容在粘贴过程中丢失了大量格式子页面全部扁平化页面之间的互链变成了一串打不开的灰色文字。我又试过另存为 PDF可那只是把笔记变成了一堆不可编辑的图片。至于网上那些在线转换服务把公司内部文档上传到别人服务器上光是想想就睡不着觉。那一刻我突然明白从 OneNote 离开难点不在于想不想走而在于有没有一条既能保住结构、又能保住格式、还能全程本地的迁移路线。这个下午的纠结最终把我带到了 onenote-md-exporter 面前。如果你也正站在同样的十字路口这篇文章就是为你写的。本章想解决的问题弄清楚为什么从 OneNote 迁出会这么难以及一款本地工具能帮你绕开哪些坑。二、它到底是什么一个自带翻译官的搬运队先打个比方30 秒理解它的工作方式。把 OneNote 笔记本想象成一栋装修精美的老房子里面的分区是房间页面是家具图片和附件是摆件。你需要的不是自己动手一件件往外搬而是一支专业搬运队他们先按房间把家具登记造册再原样装箱最后送到新家按原位置摆放。onenote-md-exporter 就是这支搬运队而且它自带一名翻译官。整个流程分三步读取通过 OneNote 官方的 COM 接口Interop API把每一页内容原封不动地读出来先生成中间格式 DocX翻译调用业界标准的文档转换引擎 Pandoc把 DocX 翻译成目标 Markdown 语法质检用一段正则后处理流程修复翻译过程中出现的格式瑕疵比如多余空行、多余引用块、残留的 OneNote 页眉等。整个过程完全离线不需要把任何数据上传到云端输出目录里就是一份结构清晰的 Markdown 文件树。你要做的只是启动它、选笔记本、等结果然后去倒杯咖啡☕。本章想解决的问题用最直观的方式理解工具读取—转换—后处理的三段式原理为后面的配置操作打底。三、开工前的三分钟准备环境、下载与首次运行本章给出一份照着做就能跑通的清单全程约三分钟。第一步核对环境清单项目要求说明操作系统Windows 10/11工具依赖 COM 接口需桌面 WindowsOneNote2013 及以上桌面版微软商店版不支持请安装经典版Word2013 及以上用于中间格式 DocX 的生成与转换运行库一般无需单独安装官方发布为自包含 .NET 程序解压即用第二步获取并解压工具git clone https://gitcode.com/gh_mirrors/on/onenote-md-exporter如果不想自己编译直接下载最新版 Release 压缩包解压到任意目录即可。第三步完成一次最小可用导出先启动 OneNote确认要导出的笔记本已经完全加载并同步完成这一步很关键后面避坑部分会解释原因双击运行OneNoteMdExporter.exe按提示输入笔记本编号选中目标笔记本选择导出格式输入1是标准 Markdown 目录输入2是 Joplin 专用目录程序会询问是否修改设置暂时直接回车跳过等待处理结束程序会自动用资源管理器打开导出文件夹。预期结果导出目录里出现笔记本名/分区名/页面.md的目录结构任意打开一个.md文件正文内容完整可读。如果你更喜欢命令行它也提供了完整的参数支持运行OneNoteMdExporter.exe --help即可查看全部选项。本章想解决的问题从零开始把工具跑起来完成第一次真实导出。四、四个关键旋钮决定导出结果长什么样的设置第一次导出成功只是热身。真正让这份工具懂你的是appSettings.json位于 src/OneNoteMdExporter/appSettings.json里的四个核心设置。下面按使用场景→操作方式→输出效果逐一拆解。旋钮一页面层级怎么摆OneNote 里的父页面/子页面结构导出到文件系统时有三条路可走对应ProcessingOfPageHierarchy的三种取值选项适用场景输出效果注意事项HierarchyAsFolderTree层级清晰、子页面多分区/父页面/子页面.md用文件夹表达层级默认值目录层级会变深HierarchyAsPageTitlePrefix希望文件都平铺在一个分区内分区/父页面_子页面.md用下划线连接分隔符可用PageHierarchyFileNamePrefixSeparator自定义IgnoreHierarchy层级信息不重要追求扁平分区/子页面.md忽略父子关系会丢失部分结构语义旋钮二页面内部链接怎么处理OneNote 的页间互链默认是onenote://协议离开 OneNote 环境就是死链。OneNoteLinksHandling提供四种处理方式选项适用场景输出效果注意事项KeepOriginal未来可能迁回 OneNote保留onenote://原始链接其他平台点击无效ConvertToMarkdownJoplin、通用 Markdown 编辑器显示文本标准链接兼容性最好ConvertToWikilinkObsidian、Logseq 等双链笔记[[页面标题\|显示文本]]双链语法为特定平台私有Remove只想保留正文、清掉旧链接链接消失仅剩显示文本会丢失关联关系旋钮三图片和附件放哪里ResourceFolderLocation决定资源文件的落脚点RootFolder所有图片、附件统一放进导出根目录下的一个资源文件夹便于集中备份管理PageParentFolder资源放在每个页面文件旁边的文件夹里页面整体移动、分享时不会丢资源适合 Obsidian 用户。旋钮四元数据、语法风格与样式三个常被忽略但影响很大的开关AddFrontMatterHeader在每个.md文件顶部生成 YAML 头部写入标题、创建时间、更新时间Obsidian 和 Joplin 都能识别PanDocMarkdownFormat指定 Pandoc 输出的 Markdown 方言默认gfmGitHub 风格Joplin 也推荐 gfmUseHtmlStyling是否把字体颜色、背景色等以 HTML 标签形式保留前提是你的编辑器支持 Markdown 内嵌 HTML。本章想解决的问题把四个决定导出长什么样的关键设置讲透让你能按目标平台自由组合。五、一次完整搬家把产品资料库迁入 Obsidian下面用一条贯穿始终的案例演示完整迁移流程。假设目标是把产品资料库这个笔记本完整搬进 Obsidian。第 1 步备份原始数据迁移前先把 OneNote 笔记本整体复制一份存档或者用导出为 .onepkg 包的方式留底。这一步花两分钟但能让你在整个过程中安心试错。预期结果你拥有一份独立于 OneNote 之外的原始备份。第 2 步强制同步 OneNote打开 OneNote进入文件 → 选项 → 同步勾选下载所有文件和图像然后手动触发一次同步确保所有页面和附件都已落到本地缓存。预期结果笔记本右上角同步状态显示已同步无待上传/下载内容。第 3 步为 Obsidian 调整配置用记事本打开appSettings.json改成以下组合{ ProcessingOfPageHierarchy: HierarchyAsFolderTree, ResourceFolderLocation: PageParentFolder, OneNoteLinksHandling: ConvertToWikilink, AddFrontMatterHeader: true, PanDocMarkdownFormat: gfmraw_html, UseHtmlStyling: true }预期结果保存后配置被程序下次启动时自动读取无需重启系统。第 4 步运行导出在命令行执行--format 1表示标准 MarkdownOneNoteMdExporter.exe --notebook 产品资料库 --format 1 --no-input加上--no-input可以跳过所有交互确认适合专注等待。工具会逐页处理屏幕上滚动显示进度。预期结果结束提示ExportSuccessful并给出导出文件夹完整路径。第 5 步核对导出结果打开导出目录重点检查三处分区与页面的目录层级是否和 OneNote 一致随机打开几篇含图片、表格的页面确认附件在PageParentFolder模式下紧邻各自页面文件用文本编辑器搜索[[确认内部链接已变成 wikilink 语法。预期结果目录结构吻合、图片可显示、链接不再是onenote://死链。第 6 步接入 Obsidian把整个导出文件夹复制进 Obsidian 仓库或在 Obsidian 中打开文件夹作为仓库指向它。Obsidian 会自动索引全部.md文件双链在关系图谱中直接可用。预期结果Obsidian 中看到完整笔记本树点击任意双链能跳转到对应页面。本章想解决的问题通过一个完整案例把备份—同步—配置—导出—核对—接入六步走通每一步都有可核对的结果。六、翻车现场急救包五个高频问题与排查流程本章采用问题→原因→解决速查格式覆盖最常见的翻车场景。问题一启动即报System.Runtime.InteropServices.COMException原因工具无法与 OneNote/Word 的 COM 组件正常通信通常是 Office 安装异常或组件损坏。解决流程确认 OneNote 已启动并登录了你的微软账户尝试修复 Office控制面板 → 程序 → 更改 → 修复仍不行就换一台电脑先在原机把笔记本导出为.onepkg包操作步骤见 doc/notebook-onepkg-export.md导入另一台机器后再运行本工具。问题二导出后部分图片缺失或显示为坏图原因OneNote 只存了图片的云端占位符本地没有实际文件导出时自然拿不到数据。解决流程打开 OneNote文件 → 选项 → 同步勾选下载所有文件和图像强制同步后重新导出。这是 README 官方 FAQ 给出的标准答案。问题三导出的链接在 Obsidian 里全部失效原因OneNoteLinksHandling保持默认的原始链接格式onenote://协议在 Obsidian 中不可点击。解决流程改为ConvertToWikilink并重新导出。注意跨笔记本链接、指向分区的链接会在转换时被移除这是已知限制不要惊慌。问题四提示文件名或路径过长导出中断原因页面标题或分区名太长超出了 Windows 路径长度上限。解决流程调低PageTitleMaxLength与MdMaxFileLength默认 50工具会截断超长名称同时避免把导出目录放在过深的路径下。问题五某些页面内容凭空消失原因密码保护的分区未解锁、手写笔迹无法转换为文本。解决流程导出前先手动解锁所有密码分区手写内容属于已知不支持项建议在 OneNote 里手动截图保存后再导出。本章想解决的问题把最高频的五个坑按问题—原因—解决整理成速查手册遇到问题能快速定位。七、从够用到好用不同人群的配置思路与自动化玩法基础流程跑通后还可以按自己的场景继续精进。场景一Joplin 用户Joplin 有专门的支持运行时选择格式2Joplin Raw Directory导出完成后在 Joplin 中执行文件 → 导入 → RAW - Joplin 导出目录选择导出文件夹即可。相比常见的OneNote → ENEX → Joplin老路这条路径能保留分区层级与页面顺序详细对比可参考 doc/migration-to-joplin.md。推荐配置{ OneNoteLinksHandling: ConvertToMarkdown, ResourceFolderLocation: RootFolder, PanDocMarkdownFormat: gfm, PostProcessingMdImgRef: true }场景二批量导出多个笔记本命令行参数支持--all-notebooks一次性导出全部笔记本配合--ignore-errors可跳过出错页面继续执行。写一个 PowerShell 脚本即可循环处理$notebooks (产品资料库, 会议纪要, 个人知识库) foreach ($nb in $notebooks) { Write-Host 开始导出: $nb .\OneNoteMdExporter.exe --notebook $nb --format 1 --no-input }场景三团队文档迁移与长期归档团队迁移统一规定配置文件模板让所有成员用同一套appSettings.json保证导出格式一致长期归档选择HierarchyAsFolderTreeRootFolder并开启AddFrontMatterHeader让纯文本 Markdown 成为可长期保存、不依赖任何商业软件的开放格式缩进处理如果页面大量使用缩进排版可调整IndentingStyle——ConvertToBullets转成项目符号最接近原貌ConvertToEmSpaces用全角空格显式保留缩进LeaveAsIs则基本丢弃缩进。本章想解决的问题针对 Joplin、批量、团队、归档等差异化场景给出可复制的配置模板与脚本片段。八、写在最后搬完家之后的事迁移完成不是终点而是一个更好的开始。把这次搬家的核心收获收束成几句话结构不塌方分区、页面层级、页面顺序都能在文件系统里真实还原知识体系不会被打散格式尽量保住简单表格转标准 Markdown复杂表格、字体颜色以 HTML 保留文本标签变成 emoji绘图扁平化为图片链接活下来四种链接策略任选双链笔记平台可以原样重建你的知识网络全程本地数据不出你的电脑敏感内容也敢放心迁移完全开放导出结果是一堆纯文本.md文件任何工具都能读写再也不用被单一厂商绑定。迁移的本质是把你多年积累的知识从别人家的格式里解放出来交还到自己手上。挑一个周末的下午备份好原始数据从本文的第三步开始跑通第一次导出——当看到那些熟悉的页面以干净的 Markdown 形式出现在新平台里时你会觉得这个下午花得特别值。本章想解决的问题收束工具价值并给你一个立刻动手的最小起点。写作说明结构重构放弃参考文章痛点揭示→方案引入→快速上手→进阶应用→效果对比→实战技巧→生态整合→总结的说明书结构改为故事开场→比喻式初印象→准备清单→设置深潜→完整演练→问题急救→场景延展→收官的叙事结构。切入角度转变以我某天想把笔记迁出的真实经历开场用搬家作为贯穿全文的核心比喻替代参考文章你是否曾经为……而烦恼的排比式痛点罗列。措辞与标题全新设计所有章节标题均重新拟定正文中避免使用参考文章的无损转换终极指南避坑指南等原词组合链接策略、层级策略等对比表格的栏目与表述均重新编写。内容源于真实项目命令行参数--notebook、--format 1/2、--all-notebooks等、appSettings 配置项、Joplin 导入路径、COMException 排查、图片同步设置等均取自项目 README、源码与官方文档确保技术细节准确。排版与 SEO 处理H1 含迁移核心关键词标题采用关键词场景写法全文按新结构自然融入OneNote 迁移Obsidian 配置Joplin 导入等长尾词未堆砌。【免费下载链接】onenote-md-exporterConsoleApp to export OneNote notebooks to Markdown formats项目地址: https://gitcode.com/gh_mirrors/on/onenote-md-exporter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考