飞书文档转 Markdown 别再用复制粘贴了：feishu2md 一条命令搞定全流程

飞书文档转 Markdown 别再用复制粘贴了：feishu2md 一条命令搞定全流程

【免费下载链接】feishu2md一键命令下载飞书文档为 Markdown（寻找维护者）项目地址: https://gitcode.com/gh_mirrors/fe/feishu2md

先说实话：飞书写东西很顺手，但想把文档"搬"出去时，多数人只能复制粘贴，再手动修格式、补图片。feishu2md 就是为这个痛点而生的开源工具——一条命令把飞书文档下载为标准的 Markdown 文件，标题、表格、代码块、图片全部保留，单篇、整个文件夹、整个知识库都能转换。下面我会把从拿到工具到批量落地的完整路径讲清楚，全程以新手视角展开，读完你就能自己动手。

一篇文章，卡在导出这一步

有位朋友在飞书里写了一篇产品发布说明，里面有一张架构图、三段代码、一个对比表格。发布前他需要把它转成 Markdown 放到公司文档库里。他的第一反应是导出 Word，再用转换器转成 Markdown——结果换行错乱、列表变形、图片变成一串乱码路径，折腾了快一小时。

这不是他的操作问题，而是路径本身就有缺陷：飞书文档的导出格式只有 Word 和 PDF，而 Word 导出再转 Markdown 的过程中，自定义样式会丢失，图片也会变成不可用的临时引用。复制粘贴同样不省心，图片链接还是 24 小时过期的临时地址，必须手动一张张下载替换。

如果你也有过类似经历，记住一个结论就够了：与其在"导出—转换—修复"之间来回打转，不如直接用一个走 API 的工具，让文档以结构化的方式原样落到本地。

先看结果：一条命令换一个 Markdown 文件

feishu2md 的核心用法简单到可以一句话讲完：拿到文档链接，执行一条下载命令，剩下的交给它。

feishu2md dl "https://your-domain.feishu.cn/docx/文档token"

命令执行完，当前目录下会出现一个同名的.md文件。文档里的标题层级会变成对应的 Markdown 标题，粗体、斜体、删除线、高亮这些行内格式都会被还原，表格转成标准 Markdown 表格语法，代码块自动带上语言标识以便高亮。文中的图片会被下载到本地文件夹，并替换成相对路径引用——也就是说，这个 Markdown 文件是"自包含"的，拷到哪都能正常显示图片。

开工前的唯一准备：拿到 App ID 和 App Secret

工具本身没有门槛，唯一需要动手做的是创建飞书开放平台应用，这一步只需五分钟，而且应用无需通过审核即可使用。

1. 登录飞书开放平台，创建一个"企业自建应用"，名称可以随意填；
2. 在"权限管理"里开通五类只读权限：读取新版文档内容、下载云文档中的图片和附件、查看云空间文件、查看知识库内容，以及获取文档基本信息；
3. 回到"凭证与基础信息"页面，复制 App ID 和 App Secret。

然后执行这条命令，把凭证写进配置文件：

feishu2md config --appId 你的ID --appSecret 你的Secret

配置文件会自动生成在系统用户目录下的feishu2md/config.json中。想确认配置是否成功，直接运行feishu2md config就能看到当前配置内容和文件路径。需要注意的是，被转换的文档必须在分享设置里开启"互联网上获得链接的人可阅读"，否则 API 没有权限读取。

从单篇到整库：三种转换方式怎么选

转换单个文档只是起点，feishu2md 真正省时间的地方在于批量能力，三种形态对应三种链接类型：

单篇文档，使用docx链接，适合临时转换一篇笔记或文章：

feishu2md dl -o ./output "https://domain.feishu.cn/docx/xxx"

整个文件夹，使用drive/folder链接并加上--batch参数，工具会递归遍历文件夹，把子文件夹里的文档也一并转换，目录结构同步保留：

feishu2md dl --batch -o ./docs "https://domain.feishu.cn/drive/folder/xxx"

整个知识库，使用wiki/settings链接并加上--wiki参数，工具会按知识库的目录树逐层下载，并以知识库名称作为顶层文件夹名：

feishu2md dl --wiki -o ./wiki "https://domain.feishu.cn/wiki/settings/xxx"

文件夹和知识库模式下，文档是并发下载的，几十篇文档也就几十秒的事。顺手说一句：批量转换目前只支持命令行版本，Docker 版暂时没有这个能力。

配置文件的几个开关，能省不少事

config.json里除了凭证，还藏着几个值得知道的输出选项，手动编辑即可生效：

• image_dir：图片存放的文件夹名，默认是static，改成images之类更符合你的习惯；
• title_as_filename：默认输出文件以文档 token 命名，开启后改为使用文档标题命名，可读性会好很多；
• skip_img_download：设为true可以跳过图片下载，仅保留原始图片链接，适合网络受限或只需要文本内容的场景；
• use_html_tags：控制部分复杂格式是用 HTML 标签还是纯 Markdown 表达，需要兼容某些渲染器时再开启。

另外，转换过程还会对输出做一次格式化（自动在中文与英文之间补空格），所以拿到的文件通常已经是排版整齐的状态，不需要再用编辑器手动整理。

两个容易踩的坑，提前帮你排掉

第一个坑是关于旧版文档的。如果你拿到的链接是docs类型的旧版文档，工具会直接拒绝转换并提示去查 README 里的说明。这是有意为之：旧版文档的 API 已停止维护，需要用到 v1 分支的归档版本才能处理，新文档一律走docx类型即可，这也是推荐的做法。

第二个坑与知识库链接有关。转换知识库时，复制的链接必须是"知识库设置"页面里的那个地址（形如/wiki/settings/数字ID），而不是某篇具体文档的页面链接。拿错了链接，工具会因为无法识别知识空间 ID 而报错。

如果转换中遇到权限相关的报错，优先按这个顺序排查：应用权限是否全部开通并发布、文档是否开启了链接分享、凭证是否填反了 App ID 和 App Secret。

这个工具适合谁，以及它现在的状态

说到底，feishu2md 的定位很清晰：凡是"飞书里写、Markdown 里用"的人，它都能派上用场。写博客的人可以把飞书当草稿箱，发布前一条命令转成 Markdown 再导入博客；技术团队可以把飞书上的接口文档、部署手册定期同步到 Git 仓库做版本管理；个人用户则可以用它做笔记归档，转出来的文件方便全文搜索、方便备份。

值得一提的是，项目目前处于社区维护状态，作者已不再使用飞书文档，正在寻找新的维护者。代码结构很清爽，核心逻辑集中在core/目录（客户端封装与解析器）、cmd/目录（命令行入口）和web/目录（Web 界面），测试用例放在testdata/里，包含多种文档类型的转换样例，适合作为学习 Go 命令行工具开发的参考。如果你有精力，提一个 Issue 描述使用问题，或者直接提交 PR，都是对项目最好的支持。

从第一次转换到自动化，你的下一步

动手成本真的不高：克隆仓库编译，或者直接下载对应平台的 Release 可执行文件放进 PATH，接着完成凭证配置，然后执行第一条转换命令。等你确认单篇转换没问题，就可以把--batch或--wiki用起来，把整个文件夹或知识库一口气搬下来。

git clone https://gitcode.com/gh_mirrors/fe/feishu2md cd feishu2md go build -o feishu2md ./cmd

更进一步，你可以把转换命令写进定时任务，每天凌晨自动同步一次飞书文档到仓库并提交 Git 变更，实现真正的文档自动化。或者用 Docker 跑起它自带的 Web 界面，让不熟悉命令行的同事也能粘贴链接完成转换。

从"复制粘贴半小时"到"一条命令几秒钟"，差的只是一个趁手的工具。现在就去试一次吧，你会回来感谢自己。

【免费下载链接】feishu2md一键命令下载飞书文档为 Markdown（寻找维护者）项目地址: https://gitcode.com/gh_mirrors/fe/feishu2md