qianran 飞书文档导出API-转Markdown项目开源
近期做扣子Agent，调用了官方的飞书插件竟然不能分享到豆包，于是本项目诞生了。
开源地址：项目首页 – 飞书文档下载提取工具:传入一个公开的飞书文档地址，自动将其转化为markdown格式，本项目调用官方接口，配备完整的官方api申请流程（普通用户也可以申请） – GitCode
飞书文档提取API
一个Node.js服务，用于提取飞书文档内容转换为Markdown格式，或获取普通网页的HTML源码。
功能特性
- 🚀 自动识别飞书文档URL
- 📝 将飞书文档转换为Markdown格式
- 🌐 获取普通网页的HTML源码
- 🔒 支持飞书API认证
- ⚡ 基于Express框架的RESTful API
安装依赖
npm install
配置
1️⃣注册飞书平台API（5分钟搞定）
如果您是第一次使用飞书API，请查看： 📖 注册知道 & 配置向导 – 包含完整的步骤说明和常见问题解答
2️⃣配置APPID和密钥（30秒搞定）
方法1：编辑.env文件（😊推荐）
- 打开项目根目录下的
.env文件 - 将示例值替换为您的真实配置：
FEISHU_APP_ID=您的真实App_ID
FEISHU_APP_SECRET=您的真实App_Secret
PORT=3000
方法2：系统环境变量（☹️不推荐） 您也可以在系统中设置环境变量：
- Windows:
set FEISHU_APP_ID=您的App_ID - Linux/Mac:
export FEISHU_APP_ID=您的App_ID
启动项目&使用
- 重启服务器：
npm start
- 内置了测试页测试API：
- 访问
http://localhost:3000 - 在测试页面输入一个飞书文档URL
- 点击 “提取内容” 按钮
- 如果配置正确，应该能成功提取文档内容
- 访问
API使用
提取内容
请求：
POST /extract
Content-Type: application/json
{
"url": "https://example.feishu.cn/docs/doccnxxxxxx"
}
响应（飞书文档）：
{
"success": true,
"type": "feishu_markdown",
"content": "# 文档标题\n\n文档内容...",
"url": "https://example.feishu.cn/docs/doccnxxxxxx"
}
响应（普通网页）：
{
"success": true,
"type": "webpage_html",
"content": "<!DOCTYPE html>...",
"url": "https://example.com"
}
健康检查
GET /health
响应：
{
"status": "ok",
"timestamp": "2024-01-01T00:00:00.000Z"
}
支持的URL格式
飞书文档
https://*.feishu.cn/docs/*https://*.feishu.cn/docx/*https://*.feishu.cn/wiki/*https://*.larksuite.com/docs/*https://*.larksuite.com/docx/*https://*.larksuite.com/wiki/*
普通网页
- 任何有效的HTTP/HTTPS URL
错误处理
所有错误响应格式：
{
"success": false,
"error": "错误描述"
}
常见错误：
400– 请求参数错误500– 服务器内部错误（如API配置错误、网络问题等）
故障排除
常见错误及解决方案
❌ “飞书API配置缺失”
原因：未正确配置飞书API凭证
解决：
- 检查
.env文件是否存在 - 确认
FEISHU_APP_ID和FEISHU_APP_SECRET已正确填写 - 重启服务器
- 查看 配置向导 获取详细步骤
❌ “获取访问令牌失败”
原因：API凭证无效或网络问题
解决：
- 验证App ID和App Secret是否正确
- 检查网络连接
- 确认飞书开放平台应用状态正常
❌ “获取文档内容失败”
原因：权限不足或文档不存在
解决：
- 确认应用有文档访问权限
- 检查文档URL是否正确
- 确认文档是公开可访问的
❌ “无法从URL中提取文档ID”
原因：URL格式不正确
解决：
- 使用飞书文档的分享链接
- 确认URL包含正确的文档ID
调试技巧
- 查看服务器日志：启动服务器后观察控制台输出
- 使用测试页面：访问
http://localhost:3000进行可视化测试 - 检查网络：确认能正常访问飞书开放平台API
- 验证权限：在飞书开放平台检查应用权限配置
常见问题解答
Q: 提示权限不足怎么办？
A: 确保您的应用有足够的权限访问目标文档，并且文档是公开可访问的。
Q: 如何获取文档的分享链接？
- 在飞书中打开文档
- 点击右上角的 “分享” 按钮
- 选择 “复制链接” 或设置为 “组织内可访问”
Q: 支持哪些类型的飞书文档？
- 新版文档 (docx)
- 旧版文档 (docs)
- 知识库文档 (wiki)
Q: 为什么有些文档无法访问？
A: 可能的原因：
- 文档权限设置为私有
- 应用权限不足
- 文档已被删除或移动
- 网络连接问题
安全提醒
⚠️ 重要安全注意事项：
- 不要将
.env文件提交到版本控制系统 - 不要在公开场所分享您的 App Secret
- 定期更换 API 凭证以确保安全
- 建议在生产环境中使用HTTPS
- 对API访问进行适当的限流控制
注意事项
- 确保飞书应用有足够的权限访问目标文档
- 飞书文档需要是公开可访问的，或者应用有相应权限
- 网页抓取可能受到目标网站的反爬虫策略影响
- 建议在生产环境中添加适当的限流和缓存机制
- 应用发布后才能正常使用API功能
- 建议定期检查飞书开放平台的API更新和变更
技术支持
如果您在使用过程中遇到问题：
- 检查 飞书开放平台文档
- 确认网络连接正常
- 验证API凭证是否正确
- 查看服务器日志获取详细错误信息
- 参考本文档的故障排除章节
许可证
MIT
