【飞书】飞书文档高效导出Markdown实战：从API配置到一键转换

1. 为什么需要将飞书文档导出为Markdown？

在日常工作中，我们经常使用飞书文档进行内容创作和团队协作。但当你需要将这些文档迁移到静态博客、GitHub Wiki、Notion等支持Markdown格式的平台时，直接复制粘贴往往会导致格式混乱。飞书官方虽然提供了PDF和Word导出功能，但这些格式在代码高亮、版本控制、内容结构化等方面都存在明显不足。

我最近在搭建个人技术博客时就遇到了这个问题。我的所有技术文档都存放在飞书上，但想要发布到Hugo静态网站时，发现格式转换特别麻烦。手动调整每个代码块、表格和标题样式，简直是一场噩梦。这时候，一个能够直接将飞书文档转为Markdown的工具就显得尤为重要。

Markdown格式的优势在于：

• 纯文本可读性：可以用任何文本编辑器打开和编辑
• 版本控制友好：与Git等工具完美配合
• 跨平台兼容：几乎所有内容平台都支持Markdown
• 轻量级标记：比HTML简单，比富文本更结构化

2. 准备工作：创建飞书自建应用

2.1 注册飞书开发者账号

首先，你需要有一个飞书账号。如果还没有，可以去飞书官网注册。注册完成后，打开飞书开放平台，点击右上角的"开发者后台"。

这里有个小技巧：即使你不是企业管理员，也可以创建"测试企业"。我刚开始以为必须要有企业权限才能开发应用，后来发现完全可以在开发者后台自己创建一个测试环境。

2.2 创建自建应用

在开发者后台，点击"创建企业自建应用"，填写基本信息：

• 应用名称：比如"Markdown导出工具"
• 应用描述：简单说明应用用途
• 应用图标：可以上传一个自定义图标

创建完成后，你会看到应用的基本信息页面。这里最重要的是两个参数：

• App ID：应用的唯一标识
• App Secret：相当于应用密码

这两个参数后面会用到，建议先复制保存到安全的地方。不过即使忘记了，随时可以回来查看。

2.3 配置API权限

这是最关键的一步。点击左侧菜单的"权限管理"，我们需要添加以下权限：

• 云文档 > 查看、评论和导出文档
• 云文档 > 查看DocX文档
• 云空间 > 查看和下载云空间中的文件

这些权限都是"只读"的，不会对文档内容做任何修改，安全性有保障。添加完权限后，记得点击"申请线上发布"。虽然我们只是在测试环境使用，但这个步骤不能跳过。

3. 安装和使用feishu2md工具

3.1 下载可执行文件

feishu2md是一个用Go语言开发的开源工具，GitHub地址在文章开头已经提供。作者很贴心地为不同平台编译好了可执行文件：

• Windows用户下载feishu2md_windows_amd64.exe
• Mac用户选择feishu2md_darwin_amd64或feishu2md_darwin_arm64(M1芯片)
• Linux用户使用feishu2md_linux_amd64

下载后，建议将文件重命名为简单的feishu2md，然后放到系统PATH包含的目录中。比如在Mac上，可以放到/usr/local/bin/目录。

3.2 配置API密钥

打开终端，运行以下命令配置你的App ID和App Secret：

bash复制feishu2md config --appId your_app_id --appSecret your_app_secret

这个命令会在用户目录下生成一个配置文件。你可以随时用feishu2md config命令查看配置是否正确。

3.3 转换第一个文档

现在可以尝试转换你的第一个飞书文档了。获取文档链接的方法：

1. 在飞书中打开要转换的文档
2. 点击右上角的"分享"
3. 开启链接分享
4. 复制链接

然后在终端运行：

bash复制feishu2md https://your-document-url.feishu.cn/docs/...

工具会自动下载文档并转换为Markdown格式，保存在当前目录下。我第一次使用时，一个10页的技术文档转换只用了不到2秒，效果非常惊艳。

4. 高级用法与技巧

4.1 处理图片和附件

默认情况下，feishu2md会将文档中的图片上传到图床服务。如果你希望本地保存图片，可以修改配置文件：

json复制{
  "image": {
    "upload": false,
    "path": "./images"
  }
}

这样图片会保存在指定的本地目录中，Markdown文件里会使用相对路径引用这些图片。这对于需要离线保存的文档特别有用。

4.2 批量转换文档

如果你需要转换大量文档，可以编写一个简单的Shell脚本：

bash复制#!/bin/bash
URLS=(
  "https://doc1.feishu.cn/docs/..."
  "https://doc2.feishu.cn/docs/..."
  "https://doc3.feishu.cn/docs/..."
)

for url in "${URLS[@]}"; do
  feishu2md "$url"
done

我团队的知识库迁移就用了这个方法，一次性转换了200多篇文档，节省了大量手动操作时间。

4.3 Docker版本部署

对于需要在服务器上运行的情况，feishu2md提供了Docker镜像。这是我常用的docker-compose.yml配置：

yaml复制version: '3'
services:
  feishu2md:
    image: wwwsine/feishu2md
    environment:
      FEISHU_APP_ID: your_app_id
      FEISHU_APP_SECRET: your_app_secret
      GIN_MODE: release
    ports:
      - "8080:8080"
    volumes:
      - ./output:/app/output

启动后，可以通过HTTP接口访问转换服务，特别适合集成到自动化流程中。

5. 常见问题排查

5.1 权限错误处理

如果遇到"Permission denied"错误，请检查：

1. 应用是否已经申请了所有必要的权限
2. 权限是否已经审核通过
3. 文档的分享设置是否为"所有人可查看"

我遇到过因为文档没有开启分享链接，导致工具无法访问的情况。飞书的权限系统比较严格，需要特别注意这一点。

5.2 格式转换问题

某些复杂的飞书文档元素可能无法完美转换为Markdown，比如：

• 嵌套表格
• 特定样式的代码块
• 复杂的排版布局

对于这种情况，我的经验是先简化文档格式，或者转换后手动调整Markdown。也可以考虑在飞书文档中使用更标准的Markdown兼容格式。

5.3 性能优化

当处理大型文档时，可能会遇到超时问题。可以通过修改配置增加超时时间：

json复制{
  "request": {
    "timeout": 60
  }
}

如果是批量处理大量文档，建议添加适当的延时，避免触发飞书的API限流机制。