告别PDF/Word！用这个开源工具把飞书文档变成可编程的Markdown
飞书文档高效转换Markdown的终极方案
每次写完飞书文档后，你是否也经历过这样的痛苦？精心排版的文档导出成PDF后变成无法编辑的"死文件"，或是转成Word后格式全乱需要重新调整。作为技术写作者，我们真正需要的是可编程、可版本控制、可跨平台渲染的纯净内容载体。而Markdown正是解决这一痛点的最佳选择。
1. 为什么Markdown是技术文档的理想格式
在内容创作领域，Markdown已经成为技术文档的事实标准格式。与PDF和Word相比，它具有几个不可替代的优势：
- 纯文本可编程性：Markdown文件可以直接被Git版本控制系统管理，方便团队协作和变更追踪
- 格式一致性：无论用何种编辑器打开，渲染效果基本一致，不会出现Word那样的兼容性问题
- 轻量级标记：简单的语法就能实现复杂排版，既保持可读性又具备丰富表现力
- 生态兼容性：几乎所有静态网站生成器（如Hugo、Hexo）和内容平台（如GitHub、知乎）都原生支持Markdown
典型应用场景：
技术博客写作 → 飞书草稿 → Markdown转换 → 发布到个人博客 产品文档协作 → 飞书编写 → Markdown导出 → 同步到GitHub Wiki 教程内容创作 → 飞书整理 → Markdown转换 → 发布到多个平台2. feishu2md工具的核心功能解析
feishu2md是一个开源工具，专门解决飞书文档导出Markdown的需求。它的核心能力包括：
2.1 完整保留文档结构
- 标题层级自动转换为Markdown的
#语法 - 有序/无序列表完美转换
- 表格转换为Markdown表格语法
- 代码块保留原语言高亮标识
转换效果对比：
| 飞书元素 | Markdown输出 |
|---|---|
| 一级标题 | # 标题 |
| 二级标题 | ## 标题 |
| 代码块 | python\nprint("hello") |
| 表格 | | Header | | ----- | | Cell | |
2.2 多媒体资源处理
- 图片自动下载并转换为相对路径引用
- 附件保留原始链接
- 支持自定义图片存储位置
提示：对于大量图片的文档，建议配置CDN或图床地址，避免本地路径依赖
2.3 多种部署方式
# 命令行版本（适合开发者） $ feishu2md https://your.feishu.doc.url # Docker版本（适合团队使用） $ docker run -p 8080:8080 wwwsine/feishu2md3. 从零开始配置feishu2md
3.1 获取飞书API凭证
- 登录飞书开发者后台
- 创建自建应用（测试模式即可）
- 开通以下权限：
- 云文档只读权限
- DocX文档查看权限
- 云空间文件下载权限
- 获取App ID和App Secret
3.2 工具安装与配置
Mac/Linux用户：
# 下载预编译二进制 $ curl -L https://github.com/Wsine/feishu2md/releases/latest/download/feishu2md-darwin-amd64 -o /usr/local/bin/feishu2md $ chmod +x /usr/local/bin/feishu2md # 配置凭证 $ feishu2md config --appId YOUR_ID --appSecret YOUR_SECRETWindows用户：
- 从Release页面下载exe文件
- 添加到PATH环境变量
- 通过PowerShell执行配置命令
4. 高级应用场景与技巧
4.1 集成到写作流水线
将feishu2md与现有工具链结合，可以实现全自动化发布：
# 示例：自动化发布脚本 import os import subprocess def convert_and_publish(doc_url): # 转换飞书文档 subprocess.run(["feishu2md", doc_url]) # 获取生成的Markdown文件名 md_file = "output.md" # 使用Hugo发布 os.system(f"cp {md_file} ~/myblog/content/posts/") os.chdir("~/myblog") os.system("hugo && git add . && git commit -m 'auto update' && git push")4.2 企业级部署方案
对于团队使用，推荐以下架构：
飞书文档 → feishu2md API服务 → Git仓库 → CI/CD流水线 → 文档网站Docker Compose配置示例：
version: '3' services: feishu2md: image: wwwsine/feishu2md environment: FEISHU_APP_ID: your_id FEISHU_APP_SECRET: your_secret ports: - "8080:8080" webhook: image: your/webhook-listener volumes: - ./scripts:/scripts4.3 样式自定义技巧
通过修改工具的配置文件，可以控制Markdown输出样式：
# ~/.feishu2md.yaml output: code_block_theme: github-dark # 代码块样式 table_style: pipe # 表格风格 image: local_path: ./images # 图片存储路径 prefix: https://cdn.example.com/ # CDN前缀5. 常见问题解决方案
Q: 转换后图片无法显示？A: 检查网络权限，确保工具能访问飞书图片服务器，或配置本地存储路径
Q: 复杂表格格式错乱？A: 飞书某些复杂表格建议先简化为基础表格结构再转换
Q: 如何批量转换多个文档？A: 编写Shell脚本循环处理，或使用feishu2md的API模式
# 批量转换示例 for url in $(cat doc_list.txt); do feishu2md $url done在实际项目中，我发现最稳定的做法是将feishu2md部署在内网服务器，通过定时任务同步团队知识库。对于超过50页的长文档，建议分章节处理以避免超时问题。