GitHub 批量下载器 (GitHub Batch Downloader)

一个功能强大的Web工具，支持仓库预览、文件树浏览、多选批量下载和代码高亮预览

📋 目录

项目简介
功能特性
技术栈
快速开始
使用指南
核心功能详解
API参考
浏览器兼容性
常见问题
开发计划
许可证

🎯 项目简介

GitHub批量下载器 是一个纯前端实现的GitHub仓库管理工具，无需后端服务，直接通过GitHub REST API与仓库交互。它解决了GitHub原生界面中无法批量选择文件下载、代码预览不便等痛点，为开发者提供一站式的仓库浏览、文件筛选、批量打包下载和代码预览体验。

核心价值

🚀 高效批量下载：支持多选文件和文件夹，一键打包为ZIP
👁️ 可视化预览：树形文件结构 + 语法高亮的代码预览
🔄 多版本支持：可切换分支、标签(Tag)、Release版本
🌍 国际化：中英文双语言界面
🎨 主题切换：深色/浅色模式，保护视力

✨ 功能特性

基础功能

功能模块	描述
仓库搜索	支持 `owner/repo` 格式或完整GitHub链接输入
仓库信息展示	显示仓库描述、Star数、Fork数、更新时间等元数据
文件树浏览	懒加载的目录树，支持展开/折叠，展示文件大小
代码预览	点击文件实时预览，支持主流编程语言语法高亮
版本切换	下拉选择分支/Tag/Release，即时刷新文件树

批量操作

功能	说明
多选文件	勾选任意文件/文件夹，支持全选/取消全选
递归文件夹	选中文件夹时自动包含其下所有文件
批量下载	使用JSZip打包为ZIP文件，保留目录结构
下载进度	实时显示打包进度和日志输出

用户体验

响应式设计，适配桌面端和移动端
下载历史记录（本地存储）
自动搜索（输入停止500ms后自动加载）
键盘快捷键支持（回车搜索）

🛠️ 技术栈

前端核心

HTML5/CSS3：语义化标签 + CSS变量主题系统
JavaScript (ES6+)：异步编程、Promise、async/await
Font Awesome 6：图标库
Highlight.js：代码语法高亮
JSZip：客户端ZIP打包

API集成

GitHub REST API v3
- 仓库信息: GET /repos/{owner}/{repo}
- 目录内容: GET /repos/{owner}/{repo}/contents/{path}
- Releases: GET /repos/{owner}/{repo}/releases
- Tags: GET /repos/{owner}/{repo}/tags
Raw GitHub：文件原始内容获取 raw.githubusercontent.com

存储

localStorage：主题偏好、语言设置、下载历史

🚀 快速开始

方式一：直接使用（无需安装）

克隆或下载本仓库
在浏览器中打开 index.html 文件
输入仓库地址（如 facebook/react）并点击"预览仓库"

方式二：本地服务器运行（推荐）

# 使用Python启动简单HTTP服务器
python -m http.server 8080

# 或使用Node.js的http-server
npx http-server -p 8080

访问 http://localhost:8080 即可使用。

方式三：在线部署

将项目部署到任何静态托管服务：

GitHub Pages
Vercel
Netlify
Cloudflare Pages

📖 使用指南

1. 搜索仓库

输入格式示例：
- facebook/react
- https://github.com/facebook/react
- git@github.com:facebook/react.git

2. 浏览文件

点击文件夹旁的 > 图标展开/折叠目录
点击文件名即可在右侧预览代码
支持的文件类型：JS/TS/Python/Java/C++/Go/Rust/HTML/CSS/JSON/Markdown等

3. 选择文件

单个选择：勾选文件前的复选框
全选：点击工具栏"全选"按钮
取消全选：点击"取消"按钮
选中文件夹时会自动递归包含所有子文件

4. 批量下载

勾选需要下载的文件/文件夹
点击"批量下载 ZIP"按钮
等待打包完成（进度条和日志显示）
自动下载ZIP压缩包，文件名格式：{owner}_{repo}_{branch}.zip

5. 切换版本

在版本下拉框中选择分支或Tag
点击"切换版本"刷新文件树

6. 界面定制

语言切换：点击右上角"中文"/"English"按钮
主题切换：点击月亮/太阳图标切换深色/浅色模式

🔧 核心功能详解

文件树懒加载机制

// 核心实现：按需加载目录内容
async function loadChildren(owner, repo, ref, path, container) {
    // 缓存已加载的目录，避免重复请求
    if (!treeCache.has(path)) {
        treeCache.set(path, await fetchDir(owner, repo, ref, path));
    }
    // 递归渲染子项...
}

优势：

减少初始API请求次数
提升大仓库的加载速度
缓存机制避免重复网络请求

批量下载递归算法

// 递归收集选中路径下的所有文件
async function collectFiles(path) {
    const item = getItemFromCache(path);
    if (item.type === "file") return [{ path }];
    
    const subs = await fetchDir(owner, repo, branch, path);
    let results = [];
    for (const sub of subs) {
        results = results.concat(await collectFiles(sub.path));
    }
    return results;
}

流程：

遍历选中的每个路径
如果是文件，直接加入任务列表
如果是文件夹，递归获取所有子文件
使用JSZip逐个添加文件
生成ZIP并触发下载

代码预览与高亮

通过 raw.githubusercontent.com 获取原始文件内容
根据文件扩展名自动识别语言类型
使用Highlight.js进行语法高亮
支持30+种编程语言

📡 API 参考

GitHub API 端点使用

端点	方法	用途	频率限制
`/repos/{owner}/{repo}`	GET	获取仓库元数据	60次/小时（未认证）
`/repos/{owner}/{repo}/contents/{path}`	GET	获取目录内容	60次/小时
`/repos/{owner}/{repo}/releases`	GET	获取发布版本	60次/小时
`/repos/{owner}/{repo}/tags`	GET	获取标签列表	60次/小时

Raw GitHub 内容获取

URL格式：https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}
示例：https://raw.githubusercontent.com/facebook/react/main/README.md

错误处理

// 统一错误处理示例
try {
    const response = await fetch(apiUrl);
    if (!response.ok) {
        if (response.status === 403) {
            throw new Error("API速率限制已达，请稍后重试");
        }
        if (response.status === 404) {
            throw new Error("仓库或文件不存在");
        }
    }
    return await response.json();
} catch (error) {
    showMessage(error.message, true);
}

🌐 浏览器兼容性

浏览器	最低版本	支持情况
Chrome	60+	✅ 完全支持
Firefox	60+	✅ 完全支持
Safari	12+	✅ 完全支持
Edge	79+	✅ 完全支持
Opera	50+	✅ 完全支持
IE	-	❌ 不支持

所需特性：

Fetch API
ES6 Promise
async/await
localStorage
CSS Grid/Flexbox

❓ 常见问题

Q1: 为什么无法加载某些仓库？

A: 可能原因：

仓库不存在或已被删除
仓库为私有仓库（本工具仅支持公开仓库）
GitHub API速率限制已到（未认证IP限制60次/小时）

Q2: 批量下载时提示"无可下载文件"？

A: 请确保：

已勾选至少一个文件或文件夹
选中的文件夹内确实包含文件
网络连接正常，能访问GitHub API

Q3: 代码预览显示乱码或无法加载？

A:

文件可能为二进制格式（如图片、PDF）
文件过大（超过5MB可能加载缓慢）
尝试切换分支后重新预览

Q4: 如何提高API速率限制？

A:

本工具为纯前端实现，无法添加认证头
如需更高限制，可自行部署并添加GitHub Personal Access Token

Q5: 下载的ZIP包中文件结构是怎样的？

A: ZIP包保留完整的仓库相对路径结构，例如：

downloaded.zip
├── src/
│   ├── index.js
│   └── utils/
│       └── helper.js
└── README.md

📅 开发计划

v2.1 (计划中)

支持GitHub Personal Access Token认证
增加文件搜索过滤功能
导出下载列表为JSON
支持断点续传

v2.2 (规划)

拖拽上传文件到仓库（需API权限）
差异对比功能
收藏常用仓库
批量下载多个仓库

📄 许可证

本项目采用 MIT License 开源协议。

MIT License

Copyright (c) 2025 GitHub Batch Downloader

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions...

🤝 贡献指南

欢迎提交Issue和Pull Request！

Fork本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启Pull Request

📧 联系方式

项目维护者：GitHub Batch Downloader Team
问题反馈：GitHub Issues
功能建议：Discussions

⭐ 如果这个工具对您有帮助，请给仓库点个Star！

Made with ❤️ for the open source community

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
index.html		index.html

Latest commit

History

Folders and files

Repository files navigation