1. 为什么飞书文档一定要折腾成markdown飞书文档给我的第一印象是“写起来很舒服”。界面干净多人协作顺手权限粒度细很多团队干脆把它当成知识库和项目文档中心来用。但一旦牵扯到“把内容拿出去”发到自己的博客、扔进Git仓库做版本管理、迁到别的知识库平台问题就来了。飞书官方导出的docx、pdf格式往往带着一堆平台自有的样式冗余粘贴到markdown编辑器里七零八落图片链接乱飞列表缩进全崩。如果你恰好维护着一套基于markdown的内容工作流中间的格式转换成本会高到让你怀疑人生。说白了markdown是内容流通里的通用格式。你的网站能渲染它Obsidian能管理它GitHub、GitLab、Gitee能直接预览它Hugo、Hexo、VitePress这些静态建站工具更是把markdown当作默认数据源。把飞书文档转成markdown等于把写好的内容从“平台私有格式”解放成“任何系统都能读的纯文本”。这也是feishu2md这类工具存在的根本理由它把飞书文档底层的block数据结构逐块翻译成标准的markdown语法而不是模拟人肉复制粘贴。实际操作中“把飞书文档内容拿出去”的常见方案大概有三种直接复制粘贴正文适合一次性搬几段纯文字但图片存活率很低表格和代码块经常碎成一团。官方导出后再用其他工具转先转docx、再转markdown步骤多、损耗大列表和标题层级容易变形。用feishu2md直接拉取转换标题、列表、代码块、图片、表格、公式都能保留成markdown实体还支持批量处理。我最终选择feishu2md就是因为它避开了一条弯路不经过任何中间格式直接从飞书API拿内容转成markdown。这篇博文想解决的也恰恰是“怎么顺利把飞书文档转换成markdown”和“转出来的文件怎么用起来”这两件事。它的目标读者很明确维护技术博客的写作者、要给团队做文档迁移的知识库管理员、习惯把所有内容沉淀在本地markdown仓库里的效率工具党。2. feishu2md的准备工作应用权限与配置很多第一次用feishu2md的人会想当然把文档链接丢进去就能出markdown。真不是这样。feishu2md不是爬虫不靠抓网页HTML解析它调用的是飞书开放平台的文档API。既然是API调用就必须先让程序拥有“读取你文档”的权限。我实际用下来十次转换失败里至少八次都是权限配置的问题。2.1 在飞书开放平台创建自建应用第一步去飞书开放平台的开发者后台创建一个“企业自建应用”。名字随意比如“文档转换机器人”然后在应用凭证页面找到App ID和App Secret这两串字符串是后续用来换取调用凭证的关键凭据相当于程序的账号密码。这里有一个容易卡住的细节如果你的飞书账号登录不了开放平台通常是因为账号没有被赋予“开发者”权限。个人版飞书或部分受限企业账号需要找团队管理员在飞书管理后台把你的账号添加上开发者角色否则浏览器会直接提示无权限进入。另外自建应用一般不需要大费周章走发布商店流程只要在应用后台完成配置就行。2.2 开通权限、发布版本、把文档分享给机器人创建应用只是一半另一半是给它开权限。飞书开放平台的权限体系很严格默认情况下新应用什么都读不了。要在“权限管理”页面搜索并开通以下几类只读权限docx相关权限用来读取文档正文内容。drive相关权限用来访问云空间文件。图片、媒体资源相关权限用来下载文档内嵌的图片。不同版本的权限项名称有细微差别搜索“docx”和“drive”前缀的权限把和“查看”“读取”“下载”相关的只读权限都勾上总没错。开通权限之后必须再“创建版本”并发布发布审批通过或者管理员同意之后权限才真正对所有API调用生效。很多人配完权限直接跑命令结果还是401、403就是因为漏了“发布”这一步。紧接着的另一个关键动作是把目标文档分享给应用对应的机器人。文档右上角点“分享”输入自建应用机器人的名称选择“可阅读”权限。feishu2md是以应用身份去读文档的如果应用对该文档没有访问权哪怕你在权限管理里开了全量只读权限单篇文档依然读不出来。这个坑我踩过全局权限开了批量转的时候部分文档被拒一查才发现那些文档从来没分享给机器人。2.3 安装feishu2md并配置环境变量安装很直接工具是Python写的pip直接装pip install feishu2md装完把App ID和App Secret塞进环境变量export FEISHU_APP_IDcli_xxxxxxxxxxxx export FEISHU_APP_SECRETxxxxxxxxxxxxxxxx如果你的文档在海外版Lark上记得加一行域名配置export FEISHU_DOMAINlarksuite.com国内飞书默认走feishu.cn不用额外设置。配置完成后建议先拿一篇短文档测试能顺利生成md再往大文档上跑。这里给一个实用建议环境变量在终端里设置只对当前会话生效关掉终端窗口就没了。与其每次敲一遍不如写进~/.zshrc或~/.bashrc或者做一个.env文件配合direnv之类的工具自动加载。我的习惯是单独维护一个feishu工具目录里面放着环境变量文件和批量转换脚本换新电脑部署也能快速恢复。3. 转换实操从命令行到产出md文件3.1 单个文档转换跑命令时参数很简单直接把飞书文档链接丢进去feishu2md https://your-domain.feishu.cn/docx/xxxxx配置正确的话工具会解析URL里的文档token通过API拉取文档的block列表再逐块翻译成markdown。完成后当前目录下会出现一个以文档标题命名的.md文件文档里用到的图片通常会被下载到同名图片目录并在md中用相对路径引用。我想强调一个体验转换结果的价值主要体现在“结构”上。正常的技术方案文档转换后#、##、###层层分明正文里的无序列表、有序列表、任务列表、引用块、代码块都有对应的markdown语法。拿到md以后我习惯先用Typora或者VS Code的preview打开扫一眼确认标题层级没有崩坏、代码块没有散架再继续后续内容加工。3.2 批量转换多个文档飞书文档一多逐个手动跑命令就不划算了。feishu2md本身能处理单个链接批量转换我一般在bash里写循环把链接列表放进一个txt文件for url in $(cat doc_urls.txt); do feishu2md $url done也可以更稳一点用Python脚本逐行读取URL每转换一个文件加个短暂间隔避免触发接口限流import subprocess import time with open(doc_urls.txt, r) as f: urls [line.strip() for line in f if line.strip()] for url in urls: print(fconverting {url}) subprocess.run([feishu2md, url]) time.sleep(1)这样处理几十个文档也就几分钟的事。转换后的md文件名来自文档标题文件名里可能有空格和特殊字符建议批量重命名成“日期-标题.md”这种格式方便归档和排序。我在迁移整套团队知识库时就先导出所有文档链接再用上面这段脚本跑了一轮之后按目录分类归档。3.3 转换后的内容长什么样我把一份包含标题、表格、代码块、公式、图片的飞书文档实际转了一遍结果大致是这样的标题飞书多级标题对应markdown的多级#这是转换最标准的环节。列表无序列表变成-开头有序列表变成1. 2. 3.任务列表变成- [ ]和- [x]。代码块语言类型标注基本能保留比如python看着很干净。表格普通表格能转成markdown表格带有合并单元格的复杂表格会退化成简化结构需要后期手补。公式飞书文档里的块级公式转出后通常保留LaTeX格式也就是markdown里$$包裹的那段内容。图片默认下载到本地md内用相对路径引用不会出现外链过期的问题。整体来看纯正文内容的转换可以做到“基本无损”但特别复杂的排版布局确实会有压缩。这不是工具的问题而是markdown这种纯文本格式的固有边界它本身就只承载结构化内容不承载精细排版。4. 转换结果不完美时怎么补救4.1 图片路径本地引用和相对路径整个转换过程中图片信息是最好处理的但也是最容易翻车的。常见情况是文档里引用了外链图片转换后md里是一堆http链接一旦外链失效图片全挂。另一种情况是应用权限里没开图片下载转换后图片全是空的。我的补救套路是统一做“图片本地化”写一段Python脚本遍历md里的标签把URL对应的图片下载到本地images目录再把md里的引用地址替换成相对路径。核心逻辑不复杂用正则找出所有图片URL。根据原文档的目录结构按序号保存图片。替换md文本中的路径为相对路径。这段脚本可以反复执行换一批文档照样用。如果你追求极致还可以反过来把图片传到图床或对象存储再用完整URL替换静态博客场景下也不会拖慢仓库体积。说到底图片路径这件事要尽早定规矩要么全本地化要么全远程混着用最容易出问题。4.2 复杂表格和公式的降级处理飞书文档里出现合并单元格非常常见但markdown原生不支持表格合并。遇到这类表格转换工具大概率会把它们变成一堆平铺文本阅读体验很差。我的处理方案分两种情况如果表格本身就是文档核心数据那我直接把原文档里的表格截图保存到md同目录并在md里注明“详见原表截图”保证信息不丢如果表格只是辅助说明就手动精简成几行markdown表格甚至列表反而更清晰。公式方面如果你用的渲染器支持LaTeX公式转出来的公式能直接显示。Typora、Obsidian、Pandoc、MathJax扩展这些主流工具默认都支持markdown公式渲染这也是为什么热搜里总有人问“markdown数学公式插件”。但要注意markdown里的_、*、^这类符号和LaTeX语法偶有冲突公式在转换后不一定被自动包裹在$或$$里。建议拿到md以后写个脚本批量检查是否有裸公式——特别是那些以“\begin{aligned}”或“\frac”开头的行如果没被公式标签包裹手动加上即可。4.3 特殊元素和能力边界飞书文档不只有纯文本。脑图、多维表格、画板、投票这一类结构化组件feishu2md读取的是docx的block结构所以它能应付常规段落但面对脑图和多维表格转换结果可能只是纯文本描述甚至直接丢失。我的经验是转换之前先在飞书里给这些特殊元素做截图把截图保存到本地转换完成后在md末尾挂上图片链接或者先手动把脑图、思维导图内容改成大纲列表把多维表格改成普通markdown表格再做转换。另一个特别容易踩的坑是超长文档。飞书API对单次拉取的block数量有限制几千行的巨型文档经常只转出一半内容。遇到这种情况先在飞书里把文档拆成几个子文档逐个转换最后在markdown里手动合并比硬跑一次要可靠得多。我的习惯是超过两千行的文档一律先拆后转。5. 把转好的markdown放进自己的内容工作流5.1 在博客和知识库里的用法转出来的markdown不应该是囤积在硬盘里的死文件它要进入你的内容生产和发布链路。我周围朋友最常见的用法有这么几种放进Git仓库用Hugo、Hexo或VitePress构建成静态博客。导入Obsidian、Logseq做个人知识管理配合双链和标签继续加工。用Pandoc继续转成PDF、Word给不习惯看md的同事交付。导入语雀、Notion这类支持markdown导入的平台实现跨平台迁移。如果你在Linux终端工作阅读markdown也很方便装一个glow或mdcat终端里就能舒服地渲染标题、列表、代码块跟看排版文档一样顺手根本不用打开图形界面。5.2 飞书内容嵌入自己网站的几种方式对比很多朋友私信问“怎么把飞书云文档内容嵌到自己网站上”。这件事有几种靠谱做法各有取舍iframe嵌入官方分享链接实现最快飞书文档现成的分享链接加上iframe标签就能用但搜索引擎几乎不会收录样式也没法改。外链跳转到飞书直接放一个“查看完整文档”的按钮跳转过去体验完整但用户跳出感强。调用飞书开放API做实时渲染文档内容实时从飞书拉取自己写前端加载block数据自由度最高开发成本也最大。feishu2md转markdown后同步发布转出来的md进入静态建站流程内容完全可控、利于SEO、便于二次加工是目前我实测最省心的方案。我的判断标准很简单如果内容需要长期反复更新并且要出现在自己的网站域名下就别把鸡蛋全放在飞书分享链接里。让飞书做“编辑后台”让markdown做“发布中间层”网站的页面生成完全由自己把控。这样飞书的协作体验保住了网站内容的可控性也保住了。5.3 团队文档同步与备份扩展到团队协作场景一套完整的工作流可以这样设计团队在飞书文档里协作写方案每天凌晨通过脚本批量拉取全部指定文档转成markdown后提交到Git仓库。仓库背后再接一个持续构建任务网站内容自动跟着更新。这个流水线同时完成了三件事内容发布、知识库更新、历史版本备份。权限上的好处也值得一提应用只有只读权限拉取过程不会误改原文档本地仓库的Git历史则相当于一份完整的文档演进记录每一版变化都有据可查。团队里有人误删了文档或者想回溯某个方案的上个版本直接从Git里恢复就可以了不必在飞书管理后台翻找恢复记录。说实话这套流程跑通以后我就不太能接受“从飞书复制粘贴到公众号再调格式”这种笨办法了。飞书在我这里变成了内容产生的源头而不是内容的终点站。最后分享几个我实操中总结的经验。第一权限配置完成后一定要先拿一个小文档试跑确认能生成md再整批操作否则批量跑一半报错会浪费大量排查时间。第二图片路径的问题尽量用脚本批量解决别手动改尤其是几十篇文档的场景。第三转换完成不等于交付完成每次拿到md后的检查清单——标题层级、代码块语言标注、公式包裹、图片是否本地化——都花几十秒扫一遍能省去后面发布时的很多麻烦。如果你手里也有大量飞书文档需要迁移或备份哪怕只是个人笔记的整理这个思路都可以直接拿过去用跑通之后“复制链接、跑命令、拿md”的三步操作会成为你最顺手的日常。