github仓库大小限制包括：普通仓库单文件≤100mb（网页上传≤25mb），公共仓建议≤1gb、超5gb触发提示，私有仓限500mb；git lfs免费账户每月10gib存储与带宽，单文件≤2gb；目录内文件数≤3000，推送频次建议≤6次/分钟；超限时可用git filter-repo瘦身；大文件应改用github releases或对象存储托管。
如果您在 GitHub 上创建或维护仓库，但发现推送失败、克隆缓慢或收到配额警告，则可能是由于仓库大小超出平台限制。以下是 GitHub 当前执行的仓库存储与容量规则说明：
一、普通仓库（非 Git LFS）的大小限制
GitHub 对普通 Git 仓库施加了明确的单文件与整体体积约束，以保障基本操作性能与服务稳定性。这些限制适用于所有免费账户，并在私有/公共仓库中差异化执行。
1、单个文件大小上限为 100 MB；若通过网页界面上传，该限制进一步收紧至 25 MB。
2、公共仓库无账户级总容量硬性封顶，但官方强烈建议单仓库保持在 1 GB 以内；超过 5 GB 将触发优化提示邮件。
3、私有仓库受更严格管控：每个私有仓库最大允许 500 MB，且不设账户级累计上限，仅按单仓计费逻辑约束。
4、磁盘上仓库总大小（含历史提交、对象数据库等）不应超过 10 GB，否则将显著拖慢克隆、提取、浏览等基础 Git 操作。
二、Git LFS 的独立配额体系
Git Large File Storage（LFS）作为大文件处理方案，其存储与带宽资源与普通仓库分离计算，启用后可规避常规仓库的 100 MB 文件拦截机制。
1、免费账户每月享有 10 GiB 存储空间 和 10 GiB 下载带宽 配额。
2、通过 LFS 追踪的单个文件最大支持 2 GB；部分资料提及上限为 5 GB，但该数值仅适用于特定企业部署场景，GitHub.com 免费层实际执行上限为 2 GB。
3、LFS 所追踪文件不计入普通仓库的 500 MB 或 1 GB 建议值，但其体积会实时扣减账户当月 LFS 配额。
4、LFS 不可用于 GitHub Pages 站点或模板仓库，且指针文件本身需符合 Git 常规文本规范。
三、目录结构与操作频率限制
除体积外，GitHub 同时对仓库内部组织方式与使用强度设限，以防止树状索引膨胀及服务过载。
1、单个目录内文件与子目录总数不得超过 3,000 个，否则将导致历史浏览与 diff 操作明显延迟。
2、每分钟向同一仓库的推送次数建议不超过 6 次；高频推送可能被临时节流或触发人工审核。
3、深度嵌套目录结构（如超过 10 层）会加剧 Git 对树对象的解析负担，官方建议采用扁平化路径划分策略。
四、历史数据清理与瘦身手段
当仓库因误提交大文件或冗余历史而超限，可通过技术干预降低其占用体积，无需升级账户类型。
1、使用 git filter-repo 或 BFG Repo-Cleaner 工具从历史提交中彻底移除指定大文件，生成精简后的提交链。
2、执行 git gc --aggressive 清理本地松散对象，并配合 git push --force-with-lease 同步瘦身结果至远程。
3、对已存在但不再需要的历史分支执行 git push origin --delete <branch-name></branch-name>，释放关联对象存储。
4、确认删除操作不可逆，所有参与协作者须重新克隆更新后的仓库，旧克隆副本将无法与新历史线合并。
五、替代性大文件分发方案
对于不适合纳入 Git 版本控制的大型资产，GitHub 明确推荐脱离 Git 体系进行托管，以规避性能与配额双重风险。
1、将数据库导出文件、视频素材、模型权重等二进制产物上传至对象存储服务（如 AWS S3、Cloudflare R2），并在 README 中提供下载链接。
2、利用 GitHub Releases 功能附加构建产物，单个 Release 可上传多个 ≤ 2 GB 的二进制附件，且不计入仓库体积统计。
3、对 CI/CD 流水线中生成的中间产物，配置缓存服务器或使用 GitHub Actions 内置缓存机制，避免反复写入仓库。
4、严禁将大型 SQL 转储文件、日志归档包、编译缓存目录纳入 Git 跟踪，此类内容应通过 .gitignore 显式排除。
