Skip to content

README.md

Latest commit

 

History

History
264 lines (175 loc) · 6 KB

README.md

File metadata and controls

264 lines (175 loc) · 6 KB
Raw

feishu-docs-export-tool

飞书在线文档批量下载工具。

一个用于批量导出飞书在线文档到本地目录的 Node.js 工具。当前实现保持原有核心链路不变：

  1. 获取 tenant_access_token
  2. 拉取目标文件夹文件清单
  3. 为在线文档创建导出任务
  4. 轮询导出状态
  5. 下载导出文件到本地

支持的主要文档类型：

  • docx
  • sheet
  • bitable

当前默认能力：

  • npm run list 仅查看文件清单
  • npm start 或 npm run download 执行批量下载
  • 顺序处理文件，便于排查问题

环境要求

  • Node.js >= 22
  • npm
  • 飞书开放平台应用凭证
  • 目标文件夹的访问权限

安装依赖：

npm install

配置

先复制环境变量模板：

cp .env.example .env

.env 示例：

FEISHU_APP_ID=your_app_id_here
FEISHU_APP_SECRET=your_app_secret_here
FEISHU_FOLDER_TOKEN=your_folder_token_here
DOWNLOAD_PATH=./downloads
POLL_INTERVAL_MS=2000

变量说明：

  • FEISHU_APP_ID：飞书应用 app_id
  • FEISHU_APP_SECRET：飞书应用 app_secret
  • FEISHU_FOLDER_TOKEN：目标文件夹 token
  • DOWNLOAD_PATH：本地下载目录，默认 ./downloads
  • POLL_INTERVAL_MS：导出任务轮询间隔，默认 2000

权限准备

在运行前，请确认应用具备云文档相关权限，并且应用本身可以访问目标文件夹中的文档。

通常至少需要检查这几项：

  • 应用已在飞书开放平台创建，并拿到 app_id / app_secret
  • 应用具备文档下载相关权限，例如 drive:file:download 或 docs:document.media:download
  • 应用被添加为目标文档或目标文件夹内文档的协作者，或通过群组继承权限

官方参考：

使用方式

仅查看文件清单：

npm run list

批量下载文档：

npm start

或：

npm run download

帮助信息：

node main.js --help

执行流程

1. 获取 tenant_access_token

调用飞书开放平台接口换取租户访问令牌：

2. 获取文件夹中文件清单

从指定文件夹分页拉取文件列表，获得文件名、类型、token 等信息：

3. 创建导出任务

对在线文档类型创建导出任务：

4. 查询导出任务状态

轮询导出任务状态，直到任务完成或失败：

5. 下载导出文件

把导出后的文件保存到本地目录：

文件类型处理规则

  • docx / sheet / bitable：创建导出任务后再下载
  • shortcut：跳过
  • file：当前实现跳过
  • 其他未知类型：记录后跳过

说明：

你提供的参考方案里提到普通文件 type=file 可以直接下载，但当前项目仍保持“核心逻辑不变”的策略，所以这一类暂时没有改成直接下载。

输出结果

程序结束后会输出执行摘要，包括：

  • 发现文件数
  • 尝试处理数
  • 成功数
  • 跳过数
  • 失败数
  • 下载目录

测试

当前项目使用 Node.js 内置测试运行器。

运行全部测试：

npm test

当前测试覆盖的是重构中最稳定、最适合自动化校验的部分：

  • 配置读取与必填校验
  • 文件名清洗
  • 本地文件保存
  • CLI 参数解析
  • 执行摘要统计

测试文件位于：

  • test/config.test.js
  • test/file-service.test.js
  • test/cli.test.js
  • test/reporting.test.js

说明：

当前还没有引入真实飞书 API 的集成测试，主要是为了避免把外部网络、权限和文档状态波动引入本地自动化测试。

常见问题排查

1. invalid param

通常优先检查：

  • .env 是否存在
  • FEISHU_APP_ID / FEISHU_APP_SECRET / FEISHU_FOLDER_TOKEN 是否为空
  • 应用凭证是否有效

参考：

2. 导出接口返回 404

优先检查：

  • 请求地址是否为 /open-apis/drive/v1/export_tasks
  • 是否误用了错误的接口路径

3. 能获取文件列表，但下载失败

优先检查：

  • 应用是否具备下载权限
  • 应用是否被加入到文档协作者
  • 目标文档是否属于应用可访问范围

4. 本地没有生成文件

优先检查：

  • DOWNLOAD_PATH 是否正确
  • 文件是否因为类型不支持而被跳过
  • 日志里是否出现失败步骤，如 create_export_task、query_export_task_status、download_exported_file

安全说明

  • 不要把 .env 提交到仓库
  • .env.example 只保留变量名，不保留真实值
  • 如果凭证曾经出现在源码、日志或聊天记录中，应立即轮换 App Secret

开源说明

  • 许可证：MIT，见 LICENSE
  • 更新记录：见 CHANGELOG.md
  • 贡献指南：见 CONTRIBUTING.md
  • 安全策略：见 SECURITY.md

项目结构

.
├── main.js
├── src
│   ├── cli.js
│   ├── config.js
│   ├── export-service.js
│   ├── feishu-client.js
│   ├── file-service.js
│   └── reporting.js
└── test
    ├── cli.test.js
    ├── config.test.js
    ├── file-service.test.js
    └── reporting.test.js

参考链接