飞书文档转 Markdown 一键搞定：feishu2md 完整上手指南，告别手动复制粘贴

飞书文档转 Markdown 一键搞定：feishu2md 完整上手指南，告别手动复制粘贴

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

深夜十一点，产品经理把 60 页的《新版本需求说明书》扔进群里，要求明早之前转成 Markdown 放进 Git 仓库。你点开飞书文档，复制、粘贴、调格式、挨个下载图片、再一张张重传……折腾到凌晨两点，表格还裂了一地。😫 这不是段子，这是每个"飞书重度用户 + Markdown 爱好者"都经历过的噩梦。

今天要安利的 feishu2md，就是专门解决"飞书文档转 Markdown"这件事的开源小工具。它用一条命令完成转换，图片、表格、代码块全部保留，全程不需要你碰一次鼠标。本文会从安装配置讲起，覆盖单篇、文件夹、知识库三种转换方式，最后附上新手最容易踩的坑，帮你十分钟内跑通完整流程。

它到底解决了什么问题

飞书官方只支持把文档导出成 Word 和 PDF。Word 版看起来能编辑，但拿 pandoc 一转换就原形毕露：冗余换行到处都是、列表层级全丢、图片变成 24 小时就过期的临时链接。手动复制粘贴更不靠谱——飞书的图片临时链接没有文件后缀，转存到图床后再想迁移，就是一场灾难。

feishu2md 换了一条路：它不走"导出再转换"的弯路，而是直接调用飞书 Open API 读取文档的底层数据块（Block），把文档结构解析后重新渲染成标准 Markdown。简单说，官方导出的是什么样它不管，它只关心文档"本来长什么样"，所以格式还原度比任何中转方案都高。

整个处理管线只有四步：解析链接提取文档 Token → 调用 API 拉取内容 → 按块解析成 Markdown → 下载图片并做本地化引用。核心逻辑集中在core/parser.go，代码量不大，逻辑清晰，这也是它成为社区项目、欢迎二次开发的原因。

十分钟上手：安装与配置

第一步：安装 feishu2md

feishu2md 用 Go 语言编写，天然跨平台。你可以在 Release 页面下载 Windows、Linux、Mac 对应的可执行文件，解压后放进 PATH 路径即可。想从源码自己编译的，clone 下来跑go build也一样。

仓库地址（需要 clone 时使用）：https://gitcode.com/gh_mirrors/fe/feishu2md

第二步：创建飞书应用并开通权限

工具本身是"壳"，真正干活的是飞书 Open API，所以需要你注册一个应用凭证。进入飞书开发者后台，创建一个"企业自建应用"，信息随便填，然后在权限管理里开通这五个权限：

权限开好后，在"凭证与基础信息"页面就能找到 App ID 和 App Secret。

第三步：写入配置

一条命令搞定，不需要手写配置文件：

feishu2md config --appId 你的AppID --appSecret 你的AppSecret

配置文件会生成在系统用户配置目录下的feishu2md/config.json。之后想确认配置是否成功，直接运行feishu2md config就能看到配置文件路径和当前内容。

到这里，你已经可以开始转换了。整个安装配置过程不超过十分钟，大部分时间都花在飞书后台点权限上。

核心用法：三种转换方式一张表看懂

feishu2md 的下载命令是feishu2md dl（download 的缩写），配合不同的参数应对不同场景。先把命令速查表放在这里，后面逐一解释：

单篇文档转换

先获取文档链接：在飞书文档里点击分享 > 开启链接分享 > 互联网上获得链接的人可阅读 > 复制链接，然后把链接丢给命令：

feishu2md dl "https://oaztcemx3k.feishu.cn/docx/DocxToken"

转换完成的.md文件会出现在当前目录，文档里的图片会自动下载到一个叫static的文件夹里，Markdown 中的引用路径也会同步改写成本地相对路径，彻底告别临时链接。

文件夹与知识库批量转换

团队迁移文档时，一条条转换显然不现实。feishu2md 的--batch模式会递归遍历文件夹里的所有子文件夹和文档，按原始目录结构落盘；--wiki模式则会把整个知识库的文档连同层级一起拉下来，转换时还会保留知识库的目录树，方便你直接搬进新的 Wiki 系统。

转换单篇文档用不到十分钟，但批量处理几十上百篇文档时，这个能力才是真正的生产力。注意一点：文件夹批量（--batch）和知识库批量（--wiki）目前不支持 Docker 版本，需要批量转换请使用命令行版本。

不想装命令行？用 Docker Web 界面

如果你只是偶尔转换一两篇，或者不想碰命令行，可以用 Docker 起一个带 Web 界面的服务：

docker run -it --rm -p 8080:8080 \ -e FEISHU_APP_ID=你的AppID \ -e FEISHU_APP_SECRET=你的AppSecret \ -e GIN_MODE=release \ wwwsine/feishu2md

启动后浏览器访问http://localhost:8080，把文档链接粘贴进输入框，点击下载就能拿到转换结果。带图片的文档会打包成 zip 供你下载，非常方便。

进阶用法：三个真实场景下的高效姿势

场景一：个人博客的自动化发布流水线

写作者把稿件放在飞书协作，发布到博客却要手动转 Markdown，这是 feishu2md 最经典的用途。配合配置文件里的title_as_filename选项，可以让输出的文件名直接用文档标题而不是一串 Token，省去重命名步骤。加上image_dir指定图片目录，输出结构就能完全对齐你博客的静态资源目录。

场景二：团队知识库的整体搬迁

迁移 200 篇文档时，先理清范围再用--wiki一把梭。转换前确认所有文档都已开启"互联网上获得链接的人可阅读"，否则 API 会因权限不足报错。转换完成后，用--dump参数可以先跑一篇做验证，检查原始 JSON 是否符合预期，避免批量跑完才发现某个权限没开对。

场景三：把文档同步塞进 CI/CD

文档团队在飞书更新，代码仓库里的文档需要跟着更新——这种"文档即代码"的诉求，feishu2md 很适合放进定时任务。每天凌晨跑一次feishu2md dl --batch -o docs/ 文件夹链接，然后用git add && git commit && git push自动提交变更，飞书和仓库就始终保持同步。图片因为已经本地化，提交到 Git 仓库后也不会出现"链接过期"的经典事故。

配置项速查：四个开关控制输出细节

配置文件config.json里除了凭证，还有一组output配置项，值得花一分钟理解：

{ "feishu": { "app_id": "...", "app_secret": "..." }, "output": { "image_dir": "static", "title_as_filename": false, "use_html_tags": false, "skip_img_download": false } }

避坑指南：新手最常踩的 4 个坑

坑一：拿着"旧版文档"链接来转

feishu2md 只支持新版文档（docx 类型）。如果你拿到的链接是/docs/开头的旧版文档，工具会直接报错。旧版转换功能已停止维护，官方保留了一个v1_support分支和 v1.4.0 归档版本可以应急，但强烈建议把文档迁移到新版后再转换。

坑二：文档没开"互联网可阅读"权限

这是报错率最高的一步。链接本身是分享出来了，但如果分享设置是"组织内可阅读"，API 照样访问不了。转换前确认文档设置为"互联网上获得链接的人可阅读"，应用也已完成发布。

坑三：图片下载失败就整篇失败

图片下载失败会导致整篇转换中断。如果你的文档图片特别多且对图片不敏感，可以临时设置skip_img_download: true先拿到文字内容，之后再单独处理图片，而不是卡在第一步。

坑四：批量转换和 Docker 的兼容性误区

Docker 版本只支持单篇文档转换，--batch和--wiki参数在 Web 界面里是不生效的。需要批量处理时，请务必使用命令行版本，别在 Docker 上浪费时间排查。

为什么值得参与这个项目

feishu2md 是一个完全开源的社区项目，作者因为不再使用飞书文档，已经把它移交社区维护，目前正在寻找维护者。它的代码结构很清晰：cmd/是命令行入口，core/是客户端和解析器，utils/是 URL 解析等工具函数，web/是 Docker 版的 Web 服务。整个核心逻辑只有几百行，是一个非常适合练手和贡献的开源项目。

你可以这样参与：

• 报 Bug：转换结果不符合预期时，用--dump把 API 原始响应存下来，连同文档链接一起提交 Issue，维护者能快速定位
• 提 PR：项目欢迎任何改进，尤其是格式解析方面的补丁
• 做维护者：项目明确在找有能力的主协调员，如果你有时间和意愿，这是接棒开源项目的好机会
• 分享用例：告诉社区你用它解决了什么问题，帮助后来者少走弯路

最后：三句话总结

feishu2md 解决的是"飞书文档转 Markdown"这个具体到不能再具体、却困扰无数人的问题：

• 一条命令：feishu2md dl 链接，图片表格代码块全保留
• 三种批量：单篇、文件夹、知识库全覆盖，目录结构原样保留
• 两个版本：命令行版适合批量与自动化，Docker Web 版适合零门槛偶尔用

如果你也在飞书和 Markdown 之间反复横跳，现在就去试试。下载工具、配好应用、贴一条链接，三分钟后你就会发现，原来文档转换可以这么简单。🚀

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