飞书文档转 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代码量不大逻辑清晰这也是它成为社区项目、欢迎二次开发的原因。十分钟上手安装与配置第一步安装 feishu2mdfeishu2md 用 Go 语言编写天然跨平台。你可以在 Release 页面下载 Windows、Linux、Mac 对应的可执行文件解压后放进 PATH 路径即可。想从源码自己编译的clone 下来跑go build也一样。仓库地址需要 clone 时使用https://gitcode.com/gh_mirrors/fe/feishu2md第二步创建飞书应用并开通权限工具本身是壳真正干活的是飞书 Open API所以需要你注册一个应用凭证。进入飞书开发者后台创建一个企业自建应用信息随便填然后在权限管理里开通这五个权限用途权限名读取文档基本信息docx:document:readonly读取文档所有块docx:document:readonly下载文档中的图片附件docs:document.media:download读取云空间文件清单drive:file:readonly读取知识库内容wiki:wiki:readonly权限开好后在凭证与基础信息页面就能找到 App ID 和 App Secret。第三步写入配置一条命令搞定不需要手写配置文件feishu2md config --appId 你的AppID --appSecret 你的AppSecret配置文件会生成在系统用户配置目录下的feishu2md/config.json。之后想确认配置是否成功直接运行feishu2md config就能看到配置文件路径和当前内容。到这里你已经可以开始转换了。整个安装配置过程不超过十分钟大部分时间都花在飞书后台点权限上。核心用法三种转换方式一张表看懂feishu2md 的下载命令是feishu2md dldownload 的缩写配合不同的参数应对不同场景。先把命令速查表放在这里后面逐一解释场景命令示例说明单篇文档feishu2md dl https://xxx.feishu.cn/docx/文档Token最常用转换到当前目录指定输出目录feishu2md dl -o ./output https://xxx.feishu.cn/docx/文档Token用 -o 指定存放位置文件夹批量feishu2md dl --batch -o docs/ https://xxx.feishu.cn/drive/folder/文件夹Token递归下载文件夹内全部文档知识库批量feishu2md dl --wiki -o wiki/ https://xxx.feishu.cn/wiki/settings/知识库Token下载整个知识库调试用feishu2md dl --dump https://...把 API 原始 JSON 响应存到本地单篇文档转换先获取文档链接在飞书文档里点击分享 开启链接分享 互联网上获得链接的人可阅读 复制链接然后把链接丢给命令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_MODErelease \ 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 } }配置项作用什么时候用image_dir图片存放目录名默认 static想集中管理图片时改个更语义化的名字title_as_filename用文档标题命名文件转换结果要直接进 Git 仓库时强烈建议开启use_html_tags复杂格式用 HTML 标签兜底遇到 Markdown 表达不了的格式时开启skip_img_download跳过图片下载只想看纯文本内容或网络受限时开启避坑指南新手最常踩的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考