1 条命令搞定飞书文档转 Markdownfeishu2md 完整上手与避坑指南【免费下载链接】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.jsonWindows 是%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_MODErelease \ wwwsine/feishu2md然后打开http://127.0.0.1:8080把文档链接粘进去浏览器直接下载转换结果含图片的文档会打包成 zip。Web 版入口逻辑在 web/main.go模板在 web/templ/index.templ.html。想定制输出的话改配置文件里的output段即可image_dir图片存放目录名默认statictitle_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），仅供参考