1 条命令搞定飞书文档转 Markdown：feishu2md 完整上手与避坑指南
【免费下载链接】feishu2md一键命令下载飞书文档为 Markdown（寻找维护者）项目地址: https://gitcode.com/gh_mirrors/fe/feishu2md
如果你正在为"飞书文档转 Markdown"这件事头疼，那么这篇文章就是为你写的。我要介绍一个叫feishu2md的开源小工具，它能把飞书文档（docx）、文件夹里的批量文档、甚至整个知识库，一键转换成结构完整的 Markdown 文件——图片自动下载、表格和代码块原样保留。下面我把自己的完整使用经历和踩过的坑都摊开讲给你听。
先讲一个我亲历的"复制粘贴噩梦"
上个月，团队要把飞书上的 40 多篇技术文档迁到内部 Wiki 系统，而那个系统只认 Markdown。于是问题来了：如何把飞书文档稳定地迁移成 Markdown？
我最初的做法，想必你也干过：打开飞书文档 → 全选复制 → 粘贴到 Typora → 发现图片全是 24 小时就失效的临时链接 → 再一张张手动下载、改名、重新插入。40 篇文档，我弄了一整天，手指头都快抽筋，最后还有 3 篇的表格彻底错位。
我当时的内心 OS 是：飞书有开放 API，为什么没有一个工具能直接"拉"文档？直到我搜到了 feishu2md，这个用 Go 写的小工具，彻底终结了这场噩梦。
feishu2md 是什么，又不是什么
一句话：feishu2md 是飞书文档到 Markdown 的"文档搬运工"——它调用飞书开放 API 读取文档内容，再把标题、列表、表格、代码块、图片全部转换成 Markdown 语法，自动写成本地文件。
它不是什么？
- 它不是在线转换网站，不要求你把文档上传给第三方；
- 它不是"复制粘贴增强器"，而是直接对接 API，拿到的就是结构化数据，不是富文本碎片；
- 它不是只能转单个文档，文件夹、知识库都能批量处理。
打个比方：以前的复制粘贴，就像你亲手把一屋子货从旧仓库搬出来，再一件件摆进新仓库；而 feishu2md 是一个带自动分拣的搬运工，把货搬过去的同时，还按"图片放这格、表格放那格"帮你摆好了货架。
第一道坎：拿到凭证并写好配置文件
要调用飞书 API，工具需要一张"通行证"——App ID 和 App Secret。去飞书开发者后台创建一个"企业自建应用"（信息随便填），然后在权限管理里开通这几项权限：
docx:document:readonly：读取新版文档内容docs:document.media:download：下载图片和附件drive:file:readonly：查看云空间文件wiki:wiki:readonly：查看知识库
接着在"凭证与基础信息"里拿到 App ID 和 App Secret，一条命令写入配置：
feishu2md config --appId YOUR_APP_ID --appSecret YOUR_APP_SECRET跑完后执行feishu2md config就能看到配置文件路径。它默认存放在系统用户配置目录下（Linux/macOS 是~/.config/feishu2md/config.json，Windows 是%AppData%\feishu2md\config.json），内容长这样：
{ "feishu": { "app_id": "YOUR_APP_ID", "app_secret": "YOUR_APP_SECRET" }, "output": { "image_dir": "static", "title_as_filename": false, "use_html_tags": false, "skip_img_download": false } }配置好之后，就可以干正事了。
核心命令：单篇文档的转换与预期产出
先拿最常用的场景练手——转换单个飞书文档。在飞书里把文档设为"互联网上获得链接的人可阅读"，复制链接，然后执行：
feishu2md dl "https://your-domain.feishu.cn/docx/文档token"加上-o可以指定输出目录：
feishu2md dl -o ./output/ "https://your-domain.feishu.cn/docx/文档token"命令跑完，你会得到：
Captured document token: xxxxxxxxxx Downloaded markdown file to ./output/xxxxxxxxxx.md输出目录里除了.md文件，还会多出一个static文件夹——所有图片已经被自动下载到里面，Markdown 里的引用路径也同步替换成了本地相对路径，彻底摆脱"图片 24 小时失效"的烦恼。转换出的文件还会经过一次 Markdown 规范化格式化，连中英文之间该不该加空格这种细节都帮你处理好了。
这一层的关键逻辑在 core/parser.go 里：标题层级、粗体斜体、下划线删除线、有序/无序/任务列表、表格、代码块（支持几十种语言的代码高亮标识）都有对应的转换规则，你在飞书里长什么样，转出来基本就是什么样。
批量转换的正确姿势：文件夹与知识库
单篇没问题了，那开头提到的 40 篇文档怎么处理？feishu2md 恰好给了两种批量模式。
文件夹批量：复制云空间里某个文件夹的分享链接，加--batch参数：
feishu2md dl --batch -o docs/ "https://your-domain.feishu.cn/drive/folder/文件夹token"它会递归遍历文件夹里的所有子文件夹和文档，目录结构原样保留，文档之间还是并发下载的，几十篇文档也就是喝杯咖啡的工夫。
知识库整库转换：打开知识库的"设置"，复制/wiki/settings/xxx形式的链接，加--wiki参数：
feishu2md dl --wiki -o wiki_docs/ "https://your-domain.feishu.cn/wiki/settings/知识库ID"知识库按节点树展开成目录结构，内部同样有并发控制（源码里最大并发数设为 10），不会把飞书 API 打爆。
新手最容易踩的 3 个坑
工具虽好，坑也不少。我把最常遇到的三个问题按"现象 → 原因 → 解法"列出来，希望你别再走弯路。
坑 1：报错 Invalid feishu/larksuite document URL pattern
- 现象：链接粘贴进去，直接报 URL 格式不合法。
- 原因：feishu2md 只认
https://域名/docx/xxx、https://域名/wiki/xxx、https://域名/drive/folder/xxx这类标准链接。你复制的可能是带#锚点、带查询参数，或者是旧版docs开头的链接。 - 解法：重新走一遍"分享 → 复制链接"，去掉多余后缀；旧版
docs文档官方已不再支持，改用新版 docx 文档。链接校验规则在 utils/url.go 里写得很清楚，感兴趣可以翻一翻。
坑 2：提示 Feishu Docs is no longer supported
- 现象：明明文档存在，工具却拒绝转换。
- 原因：这是飞书旧版文档（
docs类型），feishu2md 主分支已放弃维护旧版，只支持新版docx。 - 解法：在飞书里把旧文档另存为/迁移成新版文档再转换。
坑 3：转换报权限不足（比如 Failed to get document）
- 现象：命令能跑，但 API 返回权限错误。
- 原因：九成是应用权限没开全，或者文档本身没开"互联网上获得链接的人可阅读"。
- 解法：回到开发者后台核对四项权限是否都已开通；去飞书里把目标文档的分享权限改为"获得链接的人可阅读"。批量转换前，最好先用单篇文档验证一次权限，免得白等一整轮。
它转得稳不稳？从源码和测试看可靠性
与其听我空口吹，不如看看项目自己提供的证据。仓库里的 testdata/ 目录放了 3 组测试样例（testdocx.1/2/3），每组都是一份飞书 API 的 JSON 响应 + 一份对应的预期 Markdown 输出，格式转换的正确性由自动化测试守着，改坏了会立刻暴露。
可靠性还体现在几个细节上：
- 图片兜底：即使某张图下载失败，Markdown 里也会保留图片占位，不会整篇崩溃；
- 文件名安全：用文档标题做文件名时，会自动把
/\:*?"<>|等非法字符替换掉（见 utils/common.go 的SanitizeFileName）； - 可调试：加
--dump参数可以把 API 原始 JSON 响应存成本地文件，方便排查"是不是飞书那边返回的数据有问题"。
至于速度：单篇文档的耗时基本取决于网络，通常秒级完成；批量模式是并发下载，理论上 40 篇文档也就一两分钟。想验证的话，自己跑一遍time feishu2md dl <链接>就有答案了。
进阶玩法：Web 界面与自定义输出
不想装命令行？项目还提供 Docker 版，自带一个极简 Web 界面，粘贴链接就能转换：
docker run -it --rm -p 8080:8080 \ -e FEISHU_APP_ID=你的ID \ -e FEISHU_APP_SECRET=你的密钥 \ -e GIN_MODE=release \ wwwsine/feishu2md然后打开http://127.0.0.1:8080，把文档链接粘进去，浏览器直接下载转换结果（含图片的文档会打包成 zip）。Web 版入口逻辑在 web/main.go，模板在 web/templ/index.templ.html。
想定制输出的话，改配置文件里的output段即可：
image_dir：图片存放目录名，默认static；title_as_filename：用文档标题命名文件（默认是 token 命名）；skip_img_download：设为true可跳过图片下载，只保留链接；use_html_tags：部分复杂格式改用 HTML 标签输出。
现在，把工具装进你的工具箱
说回开头那个问题：如何把飞书文档稳定地迁移成 Markdown？答案就是三条命令——config写入凭证、dl转换单篇、dl --batch / --wiki批量搬运。以前我一整天干不完的活，现在一条命令几分钟收工；图片不再过期，表格不再错位，文档能直接进 Git 做版本管理，也能一键发布到任何支持 Markdown 的博客或 Wiki。
那个"复制粘贴一整天、图片第二天全挂"的痛点，如今已经彻底从我的工作流里消失了。工具是开源且免费的，想要体验的话，克隆仓库即可：
git clone https://gitcode.com/gh_mirrors/fe/feishu2md值得一提的是，原作者已不再使用飞书，项目正由社区维护、寻找新的维护者——如果你在用的过程中修了 bug、加了功能，欢迎直接提 PR。好的工具，值得被更多人一起打磨下去。
【免费下载链接】feishu2md一键命令下载飞书文档为 Markdown（寻找维护者）项目地址: https://gitcode.com/gh_mirrors/fe/feishu2md
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
