告别复制粘贴：用 feishu2md 三步搞定飞书文档转 Markdown
告别复制粘贴：用 feishu2md 三步搞定飞书文档转 Markdown
【免费下载链接】feishu2md一键命令下载飞书文档为 Markdown（寻找维护者）项目地址: https://gitcode.com/gh_mirrors/fe/feishu2md
深夜十一点，阿杰盯着屏幕上的飞书文档发愁。这是一份四十多页的技术方案，明天要同步到团队 Git 仓库，而仓库只认 Markdown。他尝试了导出 Word 再转格式，结果表格全乱、图片丢失、代码块缩进成一团；手动复制粘贴倒是可行，但四十分钟后他还在跟临时图片链接搏斗——那些链接只有 24 小时有效期。
你是不是也遇到过类似的场景？飞书文档写起来顺手，导出却成了老大难。今天要介绍的 feishu2md，就是一个用 Go 写成的开源小工具，专治"飞书文档转 Markdown"这件事，一条命令搞定，不用跟格式较劲。
为什么飞书文档导出 Markdown 这么麻烦
先说清楚问题根源，你才能理解这个工具的价值。
飞书官方只支持导出 Word 和 PDF 两种格式。Word 导出后再用转换工具处理，会踩三个坑：
- 样式错乱：飞书用自定义样式而非标准富文本样式，转换后列表消失、换行冗余
- 图片失效：复制粘贴得到的图片链接是临时的，24 小时后全部过期
- 代码块损坏：缩进和语言标记经常丢失，还得手动修
说白了，手动方案的本质是"用时间换格式"，文档越长越痛苦。feishu2md 的思路完全不同——它不碰导出功能，而是直接通过飞书开放平台的 API 读取文档结构，在本地重新渲染成 Markdown，相当于绕过了所有中间环节。
三步完成飞书文档转 Markdown 配置
上手成本比你想象的低，整个过程只需要三条命令。
第一步：创建飞书应用并开通权限
去飞书开发者后台创建一个"企业自建应用"，然后开通四类权限：查看新版文档（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.json，运行feishu2md config可以随时查看路径和当前配置。以后再也不用重复输入凭证。
第三步：转换文档
feishu2md dl "https://domain.feishu.cn/docx/docxtoken"文档链接通过"分享 > 开启链接分享 > 互联网上获得链接的人可阅读 > 复制链接"获取，转换完成的 .md 文件直接落在当前目录。
整个流程走下来不到三分钟，多数时间花在申请权限上，真正的转换是秒级的。
一条命令的三种形态：单篇、文件夹与知识库
feishu2md 的命令行设计得很克制，核心就一个dl（download）子命令，但通过两个开关覆盖了三种使用场景。
| 场景 | 命令 | 适用对象 |
|---|---|---|
| 单篇文档 | feishu2md dl <docx链接> | 单篇零散文档 |
| 批量文件夹 | feishu2md dl --batch -o docs/ <文件夹链接> | 云空间某个目录 |
| 整个知识库 | feishu2md dl --wiki -o wiki_docs/ <知识库链接> | Wiki 全部页面 |
值得说的是批量模式的细节：文件夹会递归遍历子目录并保持目录结构，知识库则按节点层级建目录，每个文档并发下载，最多 10 个并发任务，几十篇文档的迁移也是分分钟的事。-o参数指定输出目录，图片会默认存到 static/ 子文件夹并自动替换为相对路径引用，拿到的 Markdown 是"开箱即用"的。
转换质量如何：它能处理哪些元素
工具核心是 core/parser.go 里的解析引擎，直接把飞书文档的块结构（Block）映射成 Markdown 语法。实测过 testdata 里的样例文档，以下元素都能较好地还原：
- 标题层级 H1-H6、粗体、斜体、删除线、行内代码
- 有序列表、无序列表、任务列表
- 表格（保持列对齐，符合 GFM 语法）
- 代码块，内置数十种语言映射，包括 Go、Python、JavaScript、SQL、YAML 等
- 图片自动下载并重写为本地相对路径
- 引用块、分割线、脚注
另外它还内置了 lute 引擎做格式化，输出的 Markdown 会自动规范空格与排版，不是那种"能看但很脏"的结果。配置文件里还能调几个开关：title_as_filename用文档标题命名文件、use_html_tags保留 HTML 标签、skip_img_download跳过图片下载。
不想装命令行？Web 版同样能用
feishu2md 还附带一个 Docker Web 版本，适合不想碰命令行的同事或非技术用户：
docker run -it --rm -p 8080:8080 \ -e FEISHU_APP_ID=your_id \ -e FEISHU_APP_SECRET=your_secret \ -e GIN_MODE=release \ wwwsine/feishu2md启动后访问 http://localhost:8080，粘贴文档链接即可转换，浏览器直接下载生成的 .md 文件或包含图片的 zip 包。团队里可以部署一个共享实例，人人都能用，不用各自申请凭证。
三个容易踩的坑与解法
坑一：提示权限不足。应用开通权限后需要发布生效，且文档必须开启"互联网上获得链接的人可阅读"。文件夹和知识库同理，链接要有对应的查看权限。
坑二：旧版 docs 文档不支持。工具只支持新版 docx 文档，遇到旧版会直接报错提示，可改用 v1.4.0 归档版本处理存量文档。
坑三：转换后格式有细微差异。飞书某些复杂排版（如嵌套表格、画板）无法 100% 还原，建议转换后快速扫一遍，这类极少数情况手动微调即可，不影响整体流程。
下一步行动清单
如果你正被飞书文档迁移困扰，不妨按这份清单走一遍：
- 花两分钟在飞书开发者后台创建应用、开通四类权限
- 用
feishu2md config写入 App ID 和 App Secret - 先拿一篇文档试转换，检查图片和表格效果
- 确认满意后，用
--batch或--wiki处理批量内容 - 需要团队协作时，部署 Docker Web 版共享入口
顺带一提，这个项目目前正在寻找社区维护者，如果你熟悉 Go 语言、想参与开源，核心代码就在 core/ 目录，测试样例在 testdata/ 目录，从修 issue 开始是个不错的切入点。
文档迁移这件事，真的不该靠复制粘贴熬到深夜。
【免费下载链接】feishu2md一键命令下载飞书文档为 Markdown（寻找维护者）项目地址: https://gitcode.com/gh_mirrors/fe/feishu2md
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考