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

GitHub免费账户仓库推送失败或上传受限，主要因触及存储与文件大小限制：普通仓库单个文件限100MB（网页上传限25MB），私有仓库存储上限500MB；Git LFS每月免费10GiB存储与带宽，单文件可达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 对象，除非等待下月重置或升级账户。