Obsidian笔记迁移到飞书：自制Markdown转换工具，高效备份同步

你是否同时使用 Obsidian 和飞书来管理知识？一个用于深度记录与网状思考，另一个用于团队协作与分享。但在两者之间迁移内容，特别是将 Obsidian 中带有复杂格式的笔记发布到飞书，常常是个令人头疼的“体力活”。

手动复制粘贴？代码块会变成普通文本，表格格式全乱，Mermaid流程图直接消失。这不仅是效率问题，更是信息保真度的灾难。

为此，我实现了一个自动化工具（Skill），核心目标就一个：一键将 Obsidian（或任何 Markdown 文件）完美转换为飞书云文档，所有格式原样保留。下面分享其原理与实现方法。

痛点分析：为什么格式会丢失？

根本原因在于两者底层格式不兼容。

• Obsidian：基于标准（及扩展）Markdown 语法，支持代码块、表格、Mermaid流程图、双向链接、Callout提示块等。
• 飞书云文档：基于自研的 Block（块）结构，虽也支持代码块、表格等元素，但其API和数据模型与Markdown完全不同。

简单来说，# 标题、`代码` 这些符号对 Obsidian 有意义，但直接粘贴到飞书富文本编辑器里，只是一串无意义的字符。我们需要的是一个可靠的“翻译官”。

解决方案：Markdown 转飞书云文档工具

这个工具的核心流程非常清晰，分为五步，本质上是进行了一次格式的“编译”。

第1步：读取 Markdown 源文件

使用 Node.js 的 fs 模块读取本地 .md 文件内容。

const mdContent = fs.readFileSync(mdPath， 'utf-8');

第2步：将 Markdown 解析为 AST (抽象语法树)

这是关键的一步，我们将文本转换为结构化的数据对象。这里使用了 mdast-util-from-markdown 库。

{
  "type": "heading",
  "depth": 1,
  "children": [{"type": "text", "value": "标题"}]
}

通过 AST，我们能精确知道哪一段是标题、哪一段是代码、表格的行列结构如何，为后续转换奠定基础。这个过程对于确保内容结构化迁移至关重要，相关的解析技巧可以在技术文档板块找到更多深入讨论。

第3步：AST 转换为飞书 Block 数组

我们需要将标准的 Markdown AST 映射为飞书云文档 API 所能识别的 Block 列表。这里可以借助或参考 feishu-markdown 这类库的思想。

映射表示例：

Markdown 元素	飞书 Block 类型
# 标题	heading1
## 标题	heading2
```code```	code
表格	table
- 列表项	bullet
> 引用	quote
---	divider
![]()	image

特殊元素处理：

• Mermaid 流程图：调用 @mermaid-js 等库将其渲染为图片，然后将图片上传并插入文档。
• Callout 提示块：可以转换为飞书的“引用”Block，并在前面加上对应的表情符号（如 💡、⚠️）来模拟效果。

第4步：调用飞书云文档 API

转换得到 Block 数组后，通过飞书开放平台提供的 API 进行写入。

1. 创建文档：调用接口创建一个空的云文档，获取唯一的文档 ID。

   POST /open-apis/docx/v1/documents

2. 写入内容：将上一步得到的 Block 数组，通过批量更新接口写入刚创建的文档中。

   PATCH /open-apis/docx/v1/documents/{document_id}/blocks/batch_update

第5步：获取并返回文档链接

API 调用成功后，即可拼装出该飞书云文档的访问链接，整个流程结束。

效果对比：手动 vs 工具

为了量化效果，我使用一篇包含 1500 字、3个代码块、2个表格和1个Mermaid流程图的笔记进行测试。

方式一：手动复制粘贴	项目	结果
耗时	~15分钟
代码块	❌ 变成纯文本，无高亮
表格	❌ 格式错乱，需手动调整
Mermaid	❌ 无法显示
内部链接	❌ 全部失效

方式二：使用本转换工具	项目	结果
耗时	~3分钟 (仅需执行一条命令)
代码块	✅ 完美保留，语法高亮
表格	✅ 完美保留，结构正确
Mermaid	✅ 自动渲染为图片插入
内部链接	✅ 转换为飞书文档链接

结论：效率提升 5 倍以上，格式保留度接近 100%。

如何使用？

前置条件

1. 一个飞书开放平台应用，用于获取调用 API 必需的 app_id 和 app_secret。
2. 本地需安装 Node.js 运行环境。

使用方法

1. 配置凭证：复制配置文件模板，并填入你的飞书应用凭据。

   cp config.example.json config.json

   编辑 config.json 文件，内容如下所示：

   {
     "appId": "你的AppID",
     "appSecret": "你的AppSecret"
   }

   

2. 执行转换：通过命令行运行工具，指定要转换的 Markdown 文件路径和想要的文档标题。

   node convert.js /path/to/your/obsidian-note.md --title “转换后的文档标题”

   等待片刻，命令行便会输出新创建的飞书云文档链接，打开即可查看格式完好的内容。

扩展应用场景

这个工具的核心是处理 Markdown，因此适用范围很广：

• Typora、VS Code 等编辑器的笔记 → 飞书
• Notion 导出的 Markdown → 飞书
• GitHub/GitLab 项目的 README.md → 飞书（用于内部技术分享）
• 事实上，任何符合标准的 Markdown 文件都可以通过它快速同步到飞书，作为备份或协作的起点。

实现这样一个工具，本质上是一次对 API 集成和格式解析的实践。它不仅能解决眼前的具体问题，其设计思路也能应用于其他文档平台间的迁移场景。如果你对使用 Node.js 实现类似的自动化流程感兴趣，不妨动手尝试，将散落各处的知识有效地聚合起来。

如果你在类似的工具开发或集成中遇到了其他有趣的问题或挑战，欢迎到云栈社区的技术板块与大家交流探讨。