如何零基础把飞书文档转成 Markdown：feishu2md 一条命令就够了

如何零基础把飞书文档转成 Markdown：feishu2md 一条命令就够了

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

周四晚上九点的工位上，老周看到产品经理在群里丢下一句话：新版 API 文档明天早上要同步到公司文档站，而那个文档站只认 Markdown。对着飞书里二十篇带图带表的文档，他差点当场崩溃——直到同事丢给他feishu2md：一个用 Go 编写、一条命令就能把飞书文档转成 Markdown 的免费开源工具。

当晚十点，二十篇文档全部转完，图片也自动进了本地文件夹。这篇指南就把这套流程完整拆开：适合谁、怎么装、怎么用，外加三个容易踩的坑。全程没有晦涩术语，跟着敲命令就行。

手动逐段搬运，和一条命令差距有多大

先搞清楚 feishu2md 到底省了什么。大多数人处理飞书文档导出，走的是同一条老路：打开文档逐段复制，图片一张张另存，表格粘贴后手工对齐，代码块缩进还常常走样。一篇十页的文档，半小时起步，还总要返工。

feishu2md 只做一件事：读取飞书文档的结构化数据，翻译成标准 Markdown。粗体、斜体、标题层级、有序无序列表、任务列表、表格、代码块、引用、图片链接，都会被一一识别并保留。

一句话总结：它把"搬文档"从手艺活变成流水线，省下的时间可以用来改文档本身。

两条命令，完成第一次转换

上手分三步，前两步是准备工作，全程不到十分钟。

第一步，拿凭证。在飞书开放平台创建企业自建应用，开通四个只读权限：读取文档内容的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，就能看到文件路径和当前内容。

第三步，转换。在飞书文档里通过"分享 > 开启链接分享 > 互联网上获得链接的人可阅读 > 复制链接"拿到链接，然后执行：

feishu2md dl "https://你的域名.feishu.cn/docx/文档token"

几秒钟后，当前目录就多了一个 Markdown 文件。到这里，你已经能正式用起来了。

不止单篇：文件夹和知识库也能整体搬家

单篇转换只是开胃菜，批量能力才是真正省时间的地方。

把飞书文件夹的分享链接交给--batch，文件夹里的全部文档会被一次性转完：

feishu2md dl --batch -o docs/ "https://你的域名.feishu.cn/drive/folder/文件夹token"

知识库同理，拿到知识库设置里的链接，加上--wiki：

feishu2md dl --wiki -o wiki_docs/ "https://你的域名.feishu.cn/wiki/settings/知识库ID"

-o指定输出目录，方便把不同来源的文档分门别类存放。

一次真实的"搬家"体验

说个实际案例。有个团队要把飞书上积累了两年的两百多篇文档迁进自建知识系统，包括接口文档、部署手册、故障排查记录，一半以上带截图和表格。按老办法，三人分工得干一周；改用--batch模式，周末一个下午全部转完，图片按配置收进static目录，再开启title_as_filename让文件名直接取文档标题，后续维护非常省心。

输出行为基本都能通过配置文件控制：image_dir指定图片目录，skip_img_download只保留链接不下载，use_html_tags让复杂格式用 HTML 标签兜底。改完保存，下一次转换自动生效。

想知道转换效果的上限？仓库的testdata/目录放着多种文档样例的原始 JSON 与转换后 Markdown 对照，可以直接当"参考答案"。

再进一步：三个小贴士

贴士一，不想装命令行就用 Docker。镜像自带一个简单 Web 界面，浏览器里粘贴链接即可转换：

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

然后打开http://localhost:8080。注意--batch批量模式目前暂不支持 Docker 版本，大批量迁移请用命令行。

贴士二，把转换挂进定时任务。文档站需要定期和飞书同步？把命令写进 cron 或 CI，每天凌晨自动拉取一遍，配合-o输出目录再交给 Git 提交，就是一份自动更新的文档快照。

贴士三，排查问题用--dump。转换结果和预期不符时，加上--dump导出飞书 API 返回的原始 JSON，对照testdata/里的样例，很快能定位是源文档还是解析的问题。

下一步做什么

feishu2md 目前处于社区维护阶段，原作者已不再重度使用飞书，项目正在寻找新的维护者——这恰好是参与开源的好时机：会用就能贡献。

• 装一个，把手头一篇文档转出来试试，顺手点个 Star；
• 遇到问题去仓库提 Issue，附上文档类型和转换结果；
• 想改代码，直接 clone：git clone https://gitcode.com/gh_mirrors/fe/feishu2md。项目结构很清晰，URL 解析在utils/url.go，API 调用在core/client.go，解析核心在core/parser.go，命令入口在cmd/，测试样例在testdata/，按图索骥即可。

飞书里写，Markdown 里存，中间这段路不该是通宵加班的地方。花十分钟配好 feishu2md，从此文档迁移就是一条命令的事。

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