GitHub仓库存储限制及免费版详解

GitHub免费账户虽无明确的总存储配额，却在仓库容量、文件大小、目录结构和操作规模等多个维度设置了严格限制——私有仓库仅限500MB、单文件不得超过100MB（网页上传更严苛至25MB）、Git LFS每月仅赠10GiB免费空间与带宽、单个目录最多3000项、推送总量上限2GB……一旦触碰这些隐形红线，你将遭遇推送失败、上传拒绝或频繁警告，却未必立刻意识到问题根源。本文深入拆解这些常被忽视的硬性边界与渐进式预警机制，帮你精准定位瓶颈、规避服务中断，并掌握清理历史、迁移大文件、优化仓库结构的实用策略——毕竟，一个“看似正常”的免费仓库，可能已在崩溃边缘悄然超载。

如果您在使用 GitHub 免费账户时发现仓库无法推送新文件、上传失败或收到容量警告，则可能是由于触及了 GitHub 对免费账户设定的存储与文件大小限制。以下是针对 GitHub 免费版仓库存储上限的具体解析：

一、普通仓库（非 Git LFS）存储限制

GitHub 对免费账户的普通仓库不设明确的账户级总磁盘配额，但对单个仓库的结构和大小施加了多项建议性与强制性限制，以保障平台整体性能与响应速度。

1、单个仓库的磁盘上大小（即 .git 文件夹压缩后大小）建议不超过 10 GB；若达到 75 GB，终端将发出 Git 警告；硬性上限为100 GB，但实际中极少允许接近该值。

2、公共仓库无明确总容量限制，但建议单个公共仓库保持在 1 GB 以内，否则可能收到来自 GitHub 支持团队的优化提示邮件。

3、私有仓库受更严格约束：每个私有仓库最大容量为 500 MB，且每个私有仓库最多支持 3 名协作者。

4、单个文件大小限制为100 MB；若通过浏览器界面上传，上限进一步降至25 MB；实测中 Git 命令行推送超过 50 MB 的文件即会触发警告。

二、Git LFS（大文件存储）配额限制

Git LFS 是 GitHub 官方推荐用于管理大型二进制文件（如音频、视频、模型权重等）的机制，其存储与带宽独立于普通仓库配额，但有明确的月度免费额度。

1、免费账户每月享有10 GiB 的 LFS 存储空间和10 GiB 的 LFS 带宽，超出后需付费购买额外配额。

2、LFS 所追踪的单个文件最大可达2 GB，且该文件不计入普通仓库的 500 MB 或 1 GB 建议限制。

3、LFS 指针文件本身极小（通常数 KB），仅保存版本标识、SHA256 哈希及文件尺寸信息，真实内容托管于 GitHub 的独立 LFS 对象存储服务中。

三、其他关键结构限制

除容量与文件大小外，GitHub 还对仓库内部结构实施多项性能导向型限制，这些限制虽不直接体现为“字节数”，但实质影响存储可用性与操作可行性。

1、单个目录内文件与子目录总数不得超过3,000 个条目，否则将显著拖慢 Git 树遍历与状态检查速度。

2、仓库目录嵌套深度不得超过50 层，过深路径会降低历史浏览与 diff 渲染效率。

3、分支总数上限为5,000 个，大量分支将增加克隆、提取及合并操作的数据传输量与服务器负担。

4、单次推送（push）操作的总数据量强制限制为2 GB，且单个 Git 对象（object）大小建议不超过 1 MB，硬性上限为 100 MB。

四、容量超限后的典型表现

当仓库接近或突破上述任一限制时，GitHub 不会立即终止服务，而是通过多层级反馈机制提示用户干预，避免不可逆的性能恶化。

1、推送大于 50 MB 的文件时，Git 客户端将在终端输出明确警告，但推送仍可成功完成；用户需自行判断是否回滚该提交。

2、仓库磁盘大小超过 75 GB 时，Git 命令行将显示“repository is too large”类提示，并建议运行 git filter-repo 或 BFG Repo-Cleaner 工具清理历史大文件。

3、私有仓库累计体积达到 500 MB 后，新文件推送将被拒绝，返回类似 “remote: error: file is too large” 的错误信息，此时必须删除旧文件或启用 LFS 才能继续写入。

4、LFS 配额耗尽后，git lfs push 操作将失败并提示 “bandwidth quota exceeded”，且无法再上传新的 LFS 对象，除非等待下月重置或升级账户。

到这里，我们也就讲完了《GitHub仓库存储限制及免费版详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！