飞书文档转 Markdown：Chrome 插件一键导出干净 .md 文件

经常有人问我，飞书文档到底怎么转成 Markdown？这个问题我太有发言权了。过去两年，我的技术方案、产品需求、例会纪要基本都写在飞书里，可一旦要把内容发到博客、扔进 Obsidian，或者提交到 GitHub，麻烦就来了。排得整整齐齐的飞书文档，复制出来之后标题、表格、代码块全乱，看起来就像一锅粥。为了不再花几十分钟手工整理，我找到了一款叫“飞书转存专家”的 Chrome 插件，专做飞书文档转 Markdown 下载。它能在浏览器内直接完成转换，把飞书文档导出成干净的 .md 文件，顺手还能把图片一起存下来。这篇博文就把我折腾出来的使用方法、配置心得、踩坑记录全部放出来，希望对你有用。

1. 为什么非要把飞书文档转成 Markdown？

1.1 飞书是协作工具，Markdown 是内容资产格式

飞书文档用的是“块编辑器”，Markdown 是“纯文本标记语言”，这俩本质上就是两种物种。块编辑器最大的优势是协作：多人同时在线编辑、评论区钉住某段文字、权限精细到单篇文档，这些体验是 Markdown 文件给不了的。但 Markdown 的优势更明显——纯文本、体积小、可以进 Git、能在 Typora、Obsidian、VS Code 里随意打开，放到 Hexo、Hugo、VuePress 里就能直接发布。

我把 Markdown 当作最终存储格式，原因很直接：飞书里写的内容是“活内容”，有协作者、有评论、有版本记录，但真正要沉淀成“内容资产”的时候，Markdown 比飞书私有格式靠谱得多。举个例子，公司内部的知识库文档从飞书迁到 GitBook 或语雀时，如果你能批量拿到 Markdown，迁移成本会低很多。问题是飞书没有提供一键导出 Markdown 的公开入口，至少对普通用户来说不够方便，所以这时候就需要一个工具来做桥接。

1.2 直接复制粘贴的“格式灾难”究竟有多可怕

最朴素的方案是：打开飞书文档，Ctrl+A 全选，Ctrl+C 复制，粘贴到 Markdown 编辑器里。结果呢？你得到的不只是乱，是那种让你怀疑人生的乱。标题层级全部丢失，原来的“标题 1”变成了普通正文；“标题 2”可能变成一个加粗段落；有序列表的编号被拍平，嵌套缩进全部消失；代码块的缩进全没了，粘贴到 IDE 里直接红一片；表格更惨，粘贴出来就是一堆竖线，到底哪一列对哪一列全靠猜；图片变成一串临时链接，过几天再打开已经失效。

我记得有一次，我在飞书里整理了一份前端性能优化方案，写得很完整，里面有三张表格和十几段代码。直接复制粘贴到语雀后，表格宽度完全错乱，代码块从第二行开始就往左顶，标题层级变成清一色的正文。我光清理那个文档就花了三十分钟，最后还漏了几处行内代码标记。这种体验相信很多人都遇到过。插件做的事情，本质上就是把飞书渲染出来的 DOM 结构重新“翻译”成标准 Markdown 语法，让你直接拿到一份能用的 .md 文件，而不是一堆残渣。

1.3 谁最需要这个工具

结合我身边的场景，我觉得这三类人最需要它。

第一类是内容创作者和技术作者。在飞书里写初稿，因为协作方便；写完以后要发到个人博客、公众号或者 GitHub，这时候需要干净的 Markdown。第二类是知识库管理员。公司飞书里积累了大量优秀文档，要把它们同步到本地知识库、在线文档系统，或者做一套可检索的资料库，Markdown 是最理想的中转格式。第三类是自动化流程使用者。现在很多人会在 Coze、Dify 这类平台里搭工作流，把 Markdown 转成 Word、生成总结、做 RAG 问答，那么飞书文档先转成 Markdown 就是整条链路的起点。

说白了，只要你的工作流里出现过“飞书内容要变成其他地方能用的内容”，你就需要一个飞书文档转 Markdown 的工具。飞书转存专家这类 Chrome 插件，正好卡在这个需求点上。

2. 飞书转存专家的工作原理与核心功能拆解

2.1 浏览器插件是如何把飞书文档“翻译”成 Markdown

我先讲原理，理解了原理，后面遇到问题才知道怎么排查。

你在 Chrome 里打开飞书文档时，页面本质是一棵 DOM 树。飞书文档里每一个标题、段落、图片、表格，最终都会渲染成 HTML 标签。飞书转存专家这类插件做的事情，就是往页面里注入一段脚本，遍历这棵 DOM 树，根据标签名和飞书特有的 class 名，把不同的块识别出来，再映射成对应的 Markdown 语法。

比如遇到 <h1> 标签，就输出一行 # ；遇到 ul 里嵌套的 li ，就生成 - 前缀；遇到 <table> ，就生成 Markdown 表格；遇到代码块容器，就尝试读取语言参数，包上三个反引号。整个过程不依赖飞书后端接口，不调用任何 API，完全在浏览器本地完成解析。这样做有一个非常大的好处：用户不需要申请开发者应用、不需要拿 Token、不需要理解飞书开放平台那一套复杂的数据结构，登录网页版飞书后直接点插件按钮就行。

有人会问，为什么不直接用飞书开放 API 来转换？API 方案确实更适合企业级批量处理，但门槛太高，而且普通用户用 API 还要处理权限审批、数据格式映射、分页拉取等一堆问题。浏览器插件方案天然适合“个人快速导出”的场景，成本低、见效快。更关键的是，你文档内容不会经过第三方服务器，只要插件本身可信，隐私方面更让人放心。

2.2 标题、列表、代码块这些元素的映射规则

飞书文档里的常见块，插件基本都会按照标准的 Markdown 语法映射。我把最常见的对应关系整理成了下面这张表：

飞书元素	Markdown 语法	插件处理细节
标题 1-6	# 到 ######	自动保留大纲层级
无序列表	- 或 *	嵌套列表会额外缩进
有序列表	1. 2.` 等	尽量保留原始编号
任务列表	- [ ] / - [x]	识别勾选状态
引用块	>	多段引用合并处理
代码块	```语言	从飞书代码块语言参数读取
行内代码	`code`	识别飞书文本中的等宽字体
粗体/斜体/删除线	** * ~~	按行内样式保留
链接	[text](url)	保留超链接目标
表格	管道表格	合并单元格会降级处理

这些看起来简单，但实际处理时有很多细节。比如多级列表的缩进，Markdown 标准里最好用两个空格或四个空格来体现层级，飞书渲染出来的嵌套结构却往往只是 DOM 层面的嵌套，直接遍历时要把缩进算清楚，否则列表层级就扁了。再比如代码块的语言，飞书里如果创建者没有给代码块指定语言，插件就只能标成 text 或 plaintext ，这是合理的选择，总比渲染成纯黑一片强。

还有一个很多人忽略的点就是换行。Markdown 的换行规则比较特殊：段落之间要用空行隔开，行内换行需要在行尾加两个空格。飞书里用户习惯直接按 Shift+Enter 换行，在转换时如果不做处理，Markdown 渲染出来会变成同一段落里挤成一团。好一点的插件会把这些“软换行”统一处理成段落分隔或行尾双空格，这也是为什么换行转换得好不好，直接影响成稿质量。

2.3 图片和附件的下载策略

飞书文档里的图片分两类：外链图片和飞书内部图片。外链图片一般是从网上复制进来的，URL 直接可用，插件可以选择原样保留链接，也可以下载到本地。飞书内部图片就复杂了，它们的 URL 通常是私有 CDN 地址，带有签名参数，有有效期。如果你只把 URL 写进 Markdown 里，过段时间链接就失效了，打开一看全是裂图。

所以插件通常提供“下载图片”的选项。它的做法是：在页面里把图片资源抓出来，通过浏览器下载逻辑保存到本地，然后在 Markdown 中用相对路径引用。常见的结果就是一个名为“文档名.md”的文件，旁边跟着一个“文档名”文件夹，里面放着所有图片。附件同理，尤其是飞书云盘里的附件，直接保留原链接可能有效期有限，不如下载下来。

我自己的习惯是：只要文档要拿去外部使用，一律勾选“下载图片”；如果只是自己临时看一眼转换效果，用相对路径和原链接都行。这里有个技巧——如果图片很多，生成一个几 MB 的图片文件夹很正常，你可以把 Markdown 文件连同文件夹一起 Git 管理，这样图片永远和文档绑定在一起，不会丢。

2.4 哪些块是处理不了的：多维表格和复杂容器

我得说句公道话，飞书转存专家这类插件并不是万能的。最典型的问题是“多维表格”，也就是飞书 Bitable。它根本不是传统意义上的 Word 表格，底层是一张在线数据库表，支持视图筛选、分组、字段类型定义，DOM 结构极其复杂，而且带懒加载。插件想把它完整还原成 Markdown 表格，基本做不到。

我遇到多维表格时的方法是：先用飞书自带的“导出 CSV”或“导出 Excel”功能把数据导出来，再用工具把 CSV 转成 Markdown 表格，或者手动整理成二维表。思维笔记、流程图、画板、第三方嵌入块也是一样的道理，插件能做的最多是保留一个链接提示你这里有复杂对象，很难做到完美还原。所以使用之前最好有预期管理：插件主要处理的是常规文档块——标题、段落、列表、表格、代码块、图片，这些场景已经覆盖了 90% 的需求。

3. 实操全流程：安装到成功转换

3.1 安装 Chrome 插件的几种方式

安装飞书转存专家，最常见的方式是去 Chrome 应用商店搜索“飞书转存专家”，找到后点击“添加到 Chrome”。这个流程很简单，这里不再啰嗦。另一种方式是开发者模式加载，适合从 GitHub 或内部渠道拿到安装包的情况。具体步骤是：先下载扩展的 zip 包并解压；然后在 Chrome 地址栏输入 chrome://extensions 打开扩展管理页；打开右上角的“开发者模式”开关；点击“加载已解压的扩展程序”，选择你解压出来的文件夹，就完成了。

这里要提一个坑：很多人拿到的插件是 .crx 文件，在最新版 Chrome 里直接拖拽安装通常会被拦截。解决办法就是先解压 crx 里的内容，再用开发者模式加载。反过来，如果你只是临时用，也可以直接下载已经解压好的文件夹，不要打包成 crx。

安全方面多说一句：能在浏览器里读取飞书页面的插件，本质上拥有你飞书页面的访问权限。安装前尽量确认来源可信，有条件的话看看它的权限说明，最好只申请飞书相关域名的读写权限。如果你从内部渠道拿到的是开源版本，花几分钟翻一下代码更放心。

3.2 首次转换操作步骤详解

安装好之后，第一次转换的流程大致如下：

1. 用 Chrome 打开飞书网页版并登录，进入你想转换的文档。
2. 等待页面完全渲染，尤其是长文档，图片和表格区域都要显示完整。
3. 点击浏览器工具栏上的插件图标，会弹出一个小面板。
4. 面板里一般会有几个选项，比如“下载图片”“保留原链接”“生成同名文件夹”等，按需勾选。
5. 点击“转换并下载”，插件开始解析页面 DOM。
6. 等待几秒钟，浏览器会下载一个 .md 文件；如果勾选了图片，还会有一个同名文件夹。
7. 用 Typora、Obsidian 或任意文本编辑器打开，检查转换结果。

整个过程看起来很简单，但有一个细节会直接影响成功率：转换前一定要滚动一下页面。飞书长文档里有大量懒加载内容，如果你打开文档后直接一动不动，点击转换，页面底部的图片可能还是占位图，根本没有加载真实地址，插件自然抓不到。我现在的习惯是一口气按 End 键滚到底，再滚回顶部，让整篇文档的图片都加载出来，然后再运行插件。这个小动作能避免 90% 的“图片缺失”问题。

3.3 关键配置项和参数怎么选择

不同版本的插件，配置项细节会有差异，但核心配置基本是这几类，我一个个说清楚。

图片路径模式。相对路径适合本地知识库，Markdown 文件和图片文件夹放在一起，Typora、Obsidian 都能正确识别。绝对路径适合把图片放在图床之后。比如你打算把 Markdown 内容发布到博客，图片已经传到 OSS 或 GitHub 图床，那么转发前把路径改成 https://... 绝对地址会更省事。插件本身如果支持“外链优先”模式，记得选上。

文件名规则。默认情况是用飞书文档标题作为文件名，方便识别。如果你的文档标题里有 / 、 \ 、 : 这些非法字符，Windows 系统下会出问题，插件通常会做字符替换。建议文件名保持英文或日期前缀，后续在 Git 管理时更友好。

换行符模式。一般默认 LF 就行，兼容性最好。只有当你非要在 Windows 记事本里裸看 .md 文件时，才考虑 CRLF，反正 Markdown 编辑器会对换行符做兼容。

是否嵌入图片。有些插件支持把图片转成 base64 直接嵌进 Markdown 文件里，这样只需要一个文件，不需要附带文件夹。但 base64 会让文件体积膨胀 30% 以上，图片一多文件会变得非常臃肿，后续编辑也会卡。我强烈不建议这么做，除非你只有一两张很小的图。

3.4 转换后如何接入 Typora、Obsidian 和 VS Code

导出 Markdown 只是第一步，接下来怎么用得顺手才是关键。

Typora 最简单，直接打开 .md 文件。如果你把图片文件夹和 .md 文件放在同一个目录下，Typora 会自动通过相对路径显示图片，不用任何额外配置。

Obsidian 需要你把这些文件放进某个 vault。Obsidian 的附件路径默认是 vault 根目录下的指定文件夹，如果插件生成的图片文件夹名字和你 Obsidian 的设置不一致，图片可能显示不出来。我的做法是：在 Obsidian 设置里把“附件默认存放路径”改成和插件一致的规则，或者转换后直接把图片文件夹挪到 Obsidian 附件目录里，再统一替换路径。

VS Code 用户建议安装“Markdown All in One”和“Markdown Preview Mermaid Support”。前者可以帮你生成目录、格式化表格、自动编号，后者让你在预览里看到 Mermaid 流程图。热词里提到“markdown preview mermaid support 预览快捷键”，其实在 VS Code 里打开预览的快捷键是 Ctrl+Shift+V ，双屏预览用 Ctrl+K V 。转换出来的 Markdown 如果要做二次编辑，VS Code 是很好用的“中转站”。

如果你还要转成 Word，可以先用 Pandoc 手动操作，也可以在 Coze、Dify 这类平台里搭一个“Markdown 转 Word”的工作流。飞书转存专家负责产出 Markdown，后续加工交给你熟悉的工具链。

4. 转换效果对比与问题排查实录

4.1 一个测试文档的前后对比

我们先看一个极简的例子。假设飞书文档里有一段会议纪要，包含标题、列表、表格、任务清单和引用。转换后的 Markdown 大概是这样的：

# 会议纪要：前端性能优化方案

## 结论

本次会议确定：

- 首屏时间要从 2.8s 降到 1.8s
- 核心 Web Vitals 必须达标

## 数据对比

| 指标 | 当前值 | 目标值 |
| --- | --- | --- |
| LCP | 2.8s | 1.8s |
| CLS | 0.12 | 0.1 |

## 待办事项

- [ ] 整理监控报表
- [ ] 优化图片加载

> 下周一同步进度。

这份 Markdown 拿到任何平台上，结构都是清晰的。标题层级清楚，列表规整，表格可以直接渲染，任务列表在支持 GFM 的平台上能显示复选框，引用块也保留了。如果你是复制粘贴，可能要花十分钟修这些格式，而插件几秒钟就能搞定，这就是工具存在的意义。

当然，现实中的文档不会这么简单，但转换结果的基本盘是这样的。如果你导出的 Markdown 和这张表差得很远，多半不是插件坏，而是源文档里用了太多“假结构”，或者存在插件不支持的特殊块。

4.2 常见问题速查表

我在使用过程中积累了不少问题，整理成速查表，你可以直接对照：

问题	可能原因	解决方法
表格错位、多列变形	飞书表格存在合并单元格或表头多行	先把表格拆成简单二维表再转换，或用 HTML 表格转换
图片全部丢失或裂图	页面图片懒加载未触发，或没有勾选下载图片	转换前滚动到底部，再运行插件；确认图片文件夹和 md 文件放在一起
代码块没有语言高亮	飞书代码块未设置语言	转换后手动在反引号后面补语言，例如 ```js
链接打不开	飞书内部链接含临时签名或权限限制	内部链接保留原链接问题不大，外部使用建议重传或改为公开链接
中文文件名乱码	系统或编辑器编码不一致	Windows 下确认保存为 UTF-8，Mac/Linux 一般没问题
长文档转换很慢或卡死	页面 DOM 太大、浏览器内存占用过高	把文档拆成几个小节分别转换；关闭无关浏览器扩展
多维表格不显示	飞书多维表格结构不是普通表格	先用飞书导出 CSV，再转成 Markdown 表格
行内代码或粗体消失	飞书文本样式是自定义字体或颜色，不是粗体标记	在飞书里使用真正加粗按钮或行内代码按钮

4.3 排查转换问题的一般套路

如果你遇到上面没列到的问题，先别急着怀疑插件坏了，按照下面这个顺序排查。

第一步，用浏览器开发者工具看看生成前的 DOM。在飞书页面上右键点击“检查”，找到出问题的那个元素，看它的标签和 class 是否和插件预期一致。飞书前端经常改版，有时候只是 class 名变了一下，老版本插件就不认识了，这种情况只能等插件更新。

第二步，看插件控制台有没有报错。在扩展管理页打开“Service Worker”或者“background page”，切换到 Console 面板，如果转换过程中有大段红色报错，把日志截图发给作者，通常能很快定位问题。

第三步，用 VS Code 或任意文本编辑器直接打开生成的 .md 文件，看原始文本而不是预览。有些问题是预览器渲染宽容，但原始文本里其实缺少某些标记。检查标题行前面是否有空格、列表是否缩进、代码块是否闭合。Markdown 语法本身就敏感，尤其是代码块，如果三个反引号没有闭合，后面所有内容都会被当成代码。

最后，如果某个文档怎么调整都无法正确转换，退而求其次：在飞书里全选复制，粘贴到纯文本编辑器，手工去掉多余空行，再根据内容重建 Markdown 结构。虽然费点时间，但至少兜底。

4.4 为什么不建议用其他替代方案

你可能想过：飞书网页版不是有“复制为 Markdown”功能吗？为什么还要装插件？我实测下来，这个内置功能可用，但非常不稳定。文档结构简单时还好，一旦出现多级表格、代码块、任务列表混排，复制出来的 Markdown 可能会出现大段空白、表格错位、图片丢失。插件在解析层面做了更多针对性处理，比我手动复制要可靠得多。

在线转换工具是另一种思路，但我极不建议你拿它处理重要文档。市面上确实有一些“飞书文档转 Markdown 在线工具”，你把内容粘贴上去就能拿到 Markdown。可你想过没有，你的文档内容已经上传到别人的服务器了。企业内部文档、个人笔记、产品方案这些内容，往第三方网站一贴，等于把自己的资料裸奔出去，风险太高。浏览器插件在本地解析，至少省掉了“内容出站”这一环。

用油猴脚本或者非 Chrome 内核的浏览器插件，也不是不行，但维护更新往往跟不上飞书的改版节奏。Chrome 生态插件作者更新频率普遍更高，社区反馈也更快，所以现在遇到这种需求，我第一反应就是上 Chrome 应用商店搜一个成熟插件，再配合自己的使用习惯做配置。

5. 经验心得与进阶玩法

5.1 在飞书里就把结构写对，转换事半功倍

很多人抱怨转换结果不理想，其实问题出在源文档结构不清晰。飞书里有不少用户习惯用“正文+加粗”来模拟标题，或者手动输入“1、2、3”来模拟有序列表，甚至用空格手动缩进模拟层级。这些视觉上的“伪结构”插件很难识别，因为 Markdown 转换依赖的是语义结构，而不是视觉效果。

我的建议是，如果你知道自己后续要把飞书文档转成 Markdown，在创建文档时就严格按照语义来写。标题用飞书真正的“标题 1”“标题 2”，列表用无序列表和有序列表按钮，任务清单用复选框，代码块用代码块功能，图片也正常上传。这样转换出来，Markdown 的目录层级和结构才是最干净的。这不仅是插件使用技巧，更是一种文档规范化习惯。

5.2 批量转换飞书文档的几个野路子

插件一次只能转换一个文档，但实际工作里经常要一次处理几十篇。批量转换我一般用这几个土办法。

第一种是用浏览器的“标签组”功能。把需要转换的文档全部用鼠标中键打开，放在一个窗口里，然后从第一个标签开始，逐个点击插件图标转换。虽然还是手工点，但标签页都排好了，至少不会遗漏。

第二种是先做“转换清单”。在飞书里建一个总文档，把待转换文档的链接以列表形式放进去，转换完一篇就打勾。配合多维表格去管理状态更好，这也是飞书多维表格的一个应用实例。转换过程中还能顺手记录哪些文档有特殊情况，避免做重复工作。

第三种是如果文档有共同的目录结构，比如都在同一知识库下面，可以先导出知识库为压缩包或结构化文件，再用脚本清洗。不过这个门槛高一些，普通用户用前两种已经够了。

5.3 用飞书转存专家搭一条“飞书到发布”的生产链路

我目前最常用的流程是这样：团队在飞书里协作写技术方案，定稿之后，我打开飞书转存专家，导出 Markdown，放进博客仓库；然后在 VS Code 里用 Markdown All in One 格式化一下表格，有需要再手动改改图片路径；最后 Git 提交，触发自动构建，发布到内部博客或者 GitHub Pages。

如果是要发给外部合作方，我会再加一个步骤：把 Markdown 通过 Pandoc 或者 Coze/Dify 工作流转成 Word。你会发现，这个流程里 Markdown 就是整个生产链路的中间货币，飞书转存专家只负责把飞书里的内容变成这种中间货币，后面怎么处理就看你自己的工具搭配了。

有一点要提醒，飞书机器人发送表格这类操作，和直接发 Markdown 文本是两回事。飞书机器人 API 在消息卡片里可以通过特殊字段展示格式化的表格，但不能直接把 Markdown 文本扔进去让机器人解析。如果你想在飞书群里发表格，通常要从 Markdown 表格转成结构化数据，再按机器人 API 要求发送。转换后的 Markdown 是很好的起点，但还要多做一步适配。

5.4 进阶：写一段小脚本二次清洗转换结果

插件生成的 Markdown 已经能用了，但如果你经常批量处理，可以用一段小脚本做二次清洗。比如统一换行符、批量调整图片路径、查找未闭合的代码块、给标题自动编号。我这里给一个简单的 Python 脚本示例，只做最基础的规范化：

import re
from pathlib import Path

def normalize_md(file_path):
    p = Path(file_path)
    text = p.read_text(encoding='utf-8')
    # 统一换行符
    text = text.replace('\r\n', '\n')
    # 过滤掉多余的空行（保留最多一个空行）
    text = re.sub(r'\n{3,}', '\n\n', text)
    # 把图片相对路径统一改成 ./images/ 开头，按需修改
    text = re.sub(r'!\[([^\]]*)\]\(((?!http)[^)]+)\)', r'![\1](./images/\2)', text)
    p.write_text(text, encoding='utf-8')

if __name__ == '__main__':
    normalize_md('output.md')

这段代码不复杂，但能解决我经常遇到的“图片路径前缀不一致”和“空行太多”问题。你也可以根据自己的目录结构改正则表达式，扩展成扫描整个目录，批量处理一批 .md 文件。要提醒的是，脚本改文件前一定先备份，尤其别在原文件上直接覆盖，我吃过一次亏，改了上百个文件名结果路径全乱了。

最后分享一个我自己的使用习惯：每次转换前，先快速滚动文档到底，让所有懒加载图片都变成真实图片，这一招能解决 90% 的图片丢失。另外，转换出来的 Markdown 我一般不会直接当最终版，而是把它当作素材中间态，进 Obsidian 二次整理，补标签、补双链，再决定发布到哪。飞书转存专家解决的是“从协作平台到内容资产”的第一步，后面怎么用，全看你的工作流怎么设计。希望这篇分享能帮你少走点弯路。