Badger4us相信大多数在 GitHub 上逛仓库的人都有过这种体验：明明只需要某一个子目录里的代码或资料，却只能对着仓库右上角的“Download ZIP”按钮干瞪眼。按下去，几百兆的包下来了，解压一看，里面九成内容跟你半毛钱关系没有。想单独下载某个文件夹？官网愣是不给入口，翻遍整个页面也没找到对应的按钮。
这篇文章就是把“GitHub 单个文件夹/目录一键下载为 ZIP”这件事彻底讲透。我从日常项目维护、资料整理、教学示例分发这些实际场景出发，整理了四条最常用的下载路线：第三方工具网站、SVN 稀疏检出、Git 部分克隆、自动化打包脚本，并把每一条的原理、完整操作步骤、适用边界和踩坑点都写清楚了。适合所有刚接触 GitHub 的新手，也适合被这个问题折磨过多次、想找个一劳永逸方案的老手。
1. 为什么官网不做这个功能：需求场景与方案思路拆解
1.1 真实场景：你其实每天都在“被迫”下载整个仓库
严格来说，GitHub 官方产品里没有一个“单独下载子目录 ZIP”的入口，但这却是个需求量极大的操作。我自己统计了一下，遇到下面几类情况时，这个需求会出现得特别频繁：
- 在开源项目里只想要某个子模块的源码，比如一个 mono-repo 里只需要
packages/utils，不想拉全部业务代码。 - 想拿官方文档仓库里的某几个 Markdown 文件或一个
docs/tutorials目录，本地做个笔记备份。 - 课程、训练营、企业内部资料习惯放在 Git 仓库里，学员只需要其中某个作业模板目录。
- 大型仓库体积动辄几个 GB，为了几十兆的目录去 clone 整仓，时间和磁盘都吃不消，还容易把开发机弄脏。
在这些场景里，大家真正需要的不是“仓库”，而是“仓库里的一个目录”。把目录内容打包成一个干净的 ZIP，是最符合直觉的交付方式。
1.2 官方没做，其实不怪产品经理
从技术角度拆解，GitHub 的 Download ZIP 本质上是调用 Git 的 archive 能力，把某个 commit（也就是某一时刻的整个仓库快照）打包输出。Git 里每个目录对应一个 tree 对象，按道理说只打包某棵子树并不是做不到——技术上完全可行。但官方迟迟没在 UI 上加这个功能，我猜核心原因是两个：一是入口设计复杂，树形文件浏览里每个目录都塞一个下载按钮，交互会很乱；二是为了控制性能，服务器如果同时应对大量“只打包部分目录”的请求，对 tree 对象的遍历开销并不小。总之，这个功能成了典型的“官方不做、社区来补”的产物。
1.3 四条路线怎么选：一个表看懂差异
既然官方不给，我们就自己想办法。社区里沉淀下来的方案主要就四条，我先把它们放在一起做个横向对比。
| 方案 | 是否需要装软件 | 是否适合超大仓库 | 是否支持私有仓库 | 学习成本 | 稳定性 |
|---|---|---|---|---|---|
| 第三方网页工具（DownGit / GitZip） | 浏览器即可 | 一般，有大小限制 | 可带 Token 支持 | 最低 | 中，依赖工具站点可用性 |
| SVN 稀疏检出 | 需安装 SVN 客户端 | 很好，不拉全量历史 | 支持，可配账号 | 低 | 高，本质是官方接口 |
| Git Sparse Checkout | 需安装 Git | 很好，推荐 | 支持 | 中 | 高，最正统的 Git 方式 |
| GitHub Actions 自动化 | 无需本机安装，仓库内配置 | 很好，无大小限制 | 支持 | 中高 | 高，适合一劳永逸 |
选方案有个基本原则：如果只是偶尔下载一两次，直接用网页工具最快；如果频繁要取一个仓库的不同子目录，或者仓库特别大，优先学 Sparse Checkout；如果这个流程要反复给别人用、要走自动化，直接上 Actions 脚本。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 方案一：第三方工具网站一键生成下载链接
2.1 工具原理：其实是一个“中间人打包服务”
这类工具网站的原理并不复杂。以老牌的 DownGit 为例，你在网页上输入仓库路径后，它会在浏览器端调用 GitHub 官方 API，递归读取目标目录下的文件树，然后逐个请求文件内容，最后在本地用 JSZip 这类库打包成 ZIP 给你下载。整个过程不需要你装任何软件，也不需要拿着 Git 命令行敲来敲去，所以成为很多新手的首选。
有一点很多人不知道：这类工具本质上是拿你本机的网络去请求 GitHub API，所以如果直连 GitHub API 速度不理想，工具整体也会拖慢。另外，由于打包是在浏览器内存里进行的，目标目录特别大（比如超过几十万个文件）时，浏览器可能会卡死，这是它的天然短板。
2.2 操作步骤：以 DownGit 为例
第一步：在 GitHub 仓库页面里，进入你想下载的那个子目录，复制浏览器地址栏里的完整路径。路径格式大概是：
code复制https://github.com/用户/仓库名/tree/main/目标目录
第二步：访问 DownGit 网站（https://minhaskamal.github.io/DownGit/#/home），在输入框里粘贴刚才复制的链接，点击 Download。它支持的格式很宽松，下面这些写法都能识别：
code复制你好github/仓库名
https://github.com/用户/仓库名/tree/main/目标目录
https://github.com/用户/仓库名/tree/develop/目标目录
第三步：等它处理完，浏览器会自动下载一个 ZIP 包。解压后，里面就是你想要的那个文件夹，路径结构默认以仓库名开头。
提示：新版 DownGit 已经支持私有仓库，只需在仓库链接后追加
?token=个人访问令牌即可。个人访问令牌在 GitHub 的 Settings -> Developer settings -> Personal access tokens 里生成，选择repo权限。但我建议私有仓库优先用后面的 SVN 或 Git 方案，因为把带 Token 的链接粘到第三方网站总有安全隐患。
2.3 工具站点不可用时怎么办：GitZip 和 URL 直改法
工具网站毕竟是社区个人维护的，偶尔会挂掉，或者对某个仓库报错。这时有两个替补思路。
替补一：安装 GitZip 浏览器插件。它支持 Chrome 和 Firefox，安装后打开 GitHub 仓库页面，鼠标悬停在任意目录上会自动出现下载图标，点击就能单目录打包下载。原理跟 DownGit 差不多，但对交互做了深度优化，而且不用复制粘贴路径。实测下来，对于中小型目录体验非常好，大目录依然会力不从心。
替补二：直接改 URL 访问一些公共封装服务。GitHub 生态里有一些第三方下载代理，会把 https://github.com/xxx/yyy/archive/分支名.zip 这类链接做加速或目录裁剪，但这类第三方域名经常变动，网上的教程鱼龙混杂，我不建议新手盲目尝试。用的时候认准知名度和口碑都稳定的域名，同时注意：不要拿这类服务下载敏感或未授权的代码仓库，尊重仓库 License 永远是第一位的。
3. 方案二：SVN 稀疏检出法，不装 Git 也能精准拉取
3.1 原理：GitHub 仓库同时也是一个 SVN 仓库
这个方案可能是很多人不知道的冷知识：GitHub 官方在仓库层面维护了一套兼容 SVN 协议的接口。也就是说，只要目标仓库是公开的，你可以用 SVN 客户端直接访问它的子目录，而不需要先完整 clone 整个仓库。SVN 的检出是“按目录”进行的，天然支持只拉取某个子路径，这正好精准命中我们的需求。
这意味着什么？意味着你甚至不需要在电脑上安装 Git（虽然我建议 Git 还是得有），只需要一个 SVN 客户端，就能做到“只要目录，不要历史，不要其他文件”。
3.2 全平台操作流程：从安装到导出
SVN 导出子目录的核心命令是 svn export，它会把远程目录的内容原封不动地拷到本地，不带 .svn 元数据，干净利落。
- Windows：安装 TortoiseSVN 或者命令行版 SlikSVN，安装时勾选 command line tools。
- macOS：新版系统已不预装 SVN，需要先装 Homebrew，然后执行
brew install subversion。 - Linux（Debian/Ubuntu 系）：
sudo apt install subversion。
装好后，命令格式如下：
bash复制svn export https://github.com/用户名/仓库名/branches/main/目标目录 ./本地目录
举一个完整例子。我想下载仓库 octocat/Hello-World 中 src/components 目录的内容：
bash复制svn export https://github.com/octocat/Hello-World/branches/master/src/components ./my-components
执行后，本地会生成一个 my-components 文件夹，里面直接就是 components 下的所有文件，没有多余的层级。如果仓库默认分支不是 master 而是 main，就把 URL 里的分支名换掉。这一步很多人会踩坑：老教程里写的是 /trunk/，那是 GitHub 早期兼容 SVN 的历史路径格式，现在的新仓库用 /branches/主分支名/ 才有效。
3.3 这个方案的优点与局限
优点非常明显：不下载 Git 历史对象，速度飞快；支持私有仓库，在 URL 里带上用户名密码或用 SVN 客户端的凭据管理即可；因为是官方兼容协议，稳定性远好于第三方网页工具。
局限主要有两个。第一，GitHub 对 SVN 协议的兼容不是全覆盖，极少数用了复杂 git 特性的仓库（比如非常规的子模块布局）可能导出异常；第二，导出的只是某个时间点的快照，不会包含提交历史——但对我们“拿个 ZIP 备份目录”的需求来说，没有历史反而是优点。
4. 方案三：Git Sparse Checkout，用标准 Git 功能精准取目录
4.1 为什么推荐它：只下载“需要的部分”
如果说 SVN 方案是借道，那 Sparse Checkout 就是 Git 自己给出的标准答案。它的核心思想是：正常 clone 仓库时，结账（checkout）阶段不把整个目录树都写进工作区，而是只“稀疏”地展开你指定的子目录。
配合 Git 的 --depth 1（浅克隆，不拉历史）和 --filter=blob:none（不下载文件内容，只下载提交和目录树骨架，等到 checkout 时才按需拉取文件），整个 clone 过程的数据量可以从几个 GB 降到几十 MB。这套组合拳是当前处理超大仓库最实用的方式。
4.2 完整命令流程：一段代码说清楚
假设仓库地址为 https://github.com/owner/repo.git，我只想要其中的 docs/guide 和 tools/scripts 两个目录。
第一步，浅克隆 + 稀疏检出模式：
bash复制git clone --depth 1 --filter=blob:none --sparse https://github.com/owner/repo.git
cd repo
第二步，设置要保留的目录。注意下面的命令是追加模式，每写一个目录，就多保留一个：
bash复制git sparse-checkout set docs/guide
git sparse-checkout add tools/scripts
第三步，检查本地结果：
bash复制ls -la
执行完 sparse-checkout set 后，工作区里就只会有 docs/guide 这个目录；执行 add 后，tools/scripts 也出现了。其他所有文件都没有进入工作区，自然也不占磁盘空间。
4.3 使用场景扩展与注意事项
这个方案最适合的场景，是“你要把整个仓库作为持续使用的项目来维护，只是平时不需要全部代码”。比如你参与一个大项目，只负责其中一个模块，用 Sparse Checkout 可以做到：本地只保留模块相关代码，但 git pull 时又能同步整个仓库的最新提交，保持 git 操作完整。
几个实际心得：
- 想临时取一个目录、用完就删，直接 clone 之后
git sparse-checkout set再手动打包，这个用法等价于“精准 ZIP”，而且文件是以原生目录结构落在磁盘上的，想怎么压缩都行。 - 如果仓库特别大且网络一般，建议
--depth 1和--filter=blob:none一起用。--filter=blob:none在 checkout 时仍需下载目标文件，但不会下载无关文件的二进制内容，省的就是这部分流量。 - 请确认本地 Git 版本在 2.25 以上，太老的版本不支持
--sparse参数，sparse-checkout命令的行为也差很多。我用git --version查一下不丢人。
5. 方案四：GitHub Actions 自动化打包，适合一劳永逸的场景
5.1 思路：把“下载目录”变成一个自动交付物
前三个方案都是在“本机执行一次”的层面解决问题，但如果你面临的是这样的场景：你要长期维护一个仓库，别人经常需要里面某个目录的最新版本，每次让人去跑 SVN 命令显然不现实。更合理的方式，是把“某个目录打包成 ZIP”做成一个自动化交付物，让别人直接在网页上下载。
实现方式是在仓库里放一个 GitHub Actions 工作流，当仓库代码更新时，自动把你指定的目录打成 ZIP，并作为 workflow artifact（构建产物）上传。这样所有需要文件的人，只需要打开仓库的 Actions 页面，点开对应的工作流，就能下载到最新打包结果。
5.2 配置示例：一个可用的 workflow 文件
在仓库根目录建 .github/workflows/zip-subdirectory.yml，内容如下：
yaml复制name: Pack Subdirectory
on:
push:
paths:
- 'docs/**'
workflow_dispatch: # 允许手动触发
jobs:
pack:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Create ZIP
run: |
mkdir -p artifact
cd docs && zip -r ../artifact/docs.zip . -x "*.DS_Store"
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: docs-zip
path: artifact/docs.zip
这个工作流做了三件事：checkout 仓库、把 docs 目录压缩、把 zip 作为 artifact 上传。每次有人修改了 docs 下的文件并推送到仓库，它就会自动重新打包。仓库成员和非成员都可以在 Actions 页面下载 artifact，无需任何命令行操作。
5.3 新增“本地小脚本”思路：不依赖 Actions 时的轻量替代
如果你不想在仓库里加 CI 配置，也可以写一个几十行的本地 Python 脚本，用 GitHub API 完成“目录遍历 + 文件下载 + 压缩打包”。核心逻辑是：
第一步，调用 git/trees 接口拿到整个仓库的文件树（分支名后面加上 ?recursive=1），返回 JSON 里每一行就是一个文件路径。
bash复制curl -L \
-H "Authorization: token 你的令牌" \
"https://api.github.com/repos/owner/repo/git/trees/main?recursive=1"
第二步，用 Python 过滤出目标目录前缀下的所有路径，逐个调用 /contents/文件路径 接口下载二进制内容。注意 API 单次请求文件大小限制在 1 MB 左右，更大的文件要改用 /git/blobs 接口，这里不展开。第三步，用标准库 zipfile 写入压缩包。
整体代码量大概七八十行，适合放进自己的常用脚本库。但说实话，能用 Actions 自动化解决的问题，就没必要自己造轮子维护脚本；只有仓库数据类型特殊、不方便上 CI 时才推荐脚本方案。
6. 常见问题与排查技巧实录
6.1 以为“能加 path 参数直接下载”，其实是个大坑
网上有零散教程声称调用 GitHub 的 API 时可以这样写：
bash复制curl -L -o 目标.zip \
"https://api.github.com/repos/owner/repo/zipball/main?path=目标目录"
我实测过，GitHub 官方 /zipball 接口并不会理会 path 参数，你以为只下载一个目录，结果拿到的还是整个仓库的压缩包。这个坑藏得很深，因为请求本身能成功，响应也是合法的 ZIP 文件，只有解压后才发现上当。判断标准很简单：解压后看看第一层目录里是不是仓库的全部根内容。如果是，那就是被这个伪参数坑了。
6.2 目标仓库太大，网页工具直接超时怎么办
第三方网页工具在后台逐个拉取文件内容，仓库大、目录文件数量多时特别容易转圈转半天然后报错。可以参考下面的处理顺序：
- 优先换 SVN 方案，这是对超大仓库最稳定的路径。
- 其次用 Sparse Checkout，把 checkout 限定到目标目录后，用本地打包工具压缩。
- 如果源仓库本身提供了发布包或者 Docs 站点的静态资源包，优先用官方发布渠道。
不要在一个网页工具上反复重试超过三次，换路线通常比死磕更有效。
6.3 仓库里混着 LFS 大文件，下载的 ZIP 里却是指针文件
很多游戏资源、设计素材仓库会用 Git LFS 管理大文件。这种情况用网页工具或普通 git clone 后，你拿到的往往不是真实文件内容，而是一个文本指针，里面是一串 SHA256 哈希和引用地址。遇到包含 .gitattributes 且里面标记了 filter=lfs 的仓库，务必小心。
解决办法：本地安装 Git LFS 插件，执行 git lfs install 和 git lfs pull 拉取真实文件。Sparse Checkout 模式下同样需要执行 git lfs pull 才会下载 LFS 文件本体。如果没有安装 LFS 条件，直接放弃网页工具，回到 SVN 方案——GitHub 的 SVN 兼容接口会自动处理 LFS 对象，返回真实文件内容。
6.4 提示“分支名不存在”或“404”的排查顺序
分别用 SVN 和 Sparse Checkout 时，最常碰到的错误就是 404。先别急着怀疑仓库私有或路径错，按照这个顺序排查：
- 确认仓库是公开还是私有，私有仓库必须带身份验证。
- 确认分支名。仓库默认分支可能是
main，也可能是master，去仓库主页看一眼就知道了。 - 确认目录路径的大小写。GitHub 上的路径是大小写敏感的，
Src/Components和src/components在非 Windows 平台是两个完全不同的路径，手敲链接最容易在这一步翻车。 - 确认不是符号链接或子模块目录。这类目录在 GitHub 网页上能正常显示，但通过 SVN 或 API 导出时表现可能异常。
我把这个排查顺序练成了一个习惯，遇到 404 先看一眼 URL，检查分支名和大小写，基本能解决九成问题。
6.5 汇成一张速查表
最后整理一张场景速查表，照着选就行：
| 用户需求 | 推荐方案 | 一句话理由 |
|---|---|---|
| 偶尔下载一两个子目录 | 网页工具 DownGit | 零学习成本，复制粘贴即可 |
| 日常工作需要高频拉取子目录 | Git Sparse Checkout | 标准 Git 方式，可同步更新 |
| 超大仓库单目录导出 | SVN export | 不拉历史对象，速度快 |
| 私有仓库子目录下载 | SVN / Git Sparse Checkout | 支持身份认证，不用把 Token 交给第三方 |
| 需要自动化交付目录 ZIP | GitHub Actions | 一劳永逸，网页直接下载产物 |
我个人这几年用下来，真正最省心的组合是：小目录用 DownGit，大仓库用 SVN export，需要长期维护的模块用 Sparse Checkout。GitHub Actions 我一般只在团队协作和对外分发时配置，因为它的构建页面本身就自带权限控制，比自己搭文件服务器安全得多。希望这份指南能帮你把“找文件夹、下载文件夹”这个高频小问题彻底变成顺手的事。