静态文件大小限制——GitHub 100MB 警告怎么处理

GitHub 的限制

PakePlus 云端打包的第一步是把项目的 dist 目录 push 到 GitHub fork 仓库。GitHub 对仓库里的文件大小有明确限制：

PakePlus 官方文档也特意提示：

单个文件大小最好不要超过 10M，因为 github 限制，例如视频或者图片最好全部使用外部链接的形式，或者使用压缩工具将文件压缩至 10M 以下。

这里文档说的是"建议 10MB 以内"，实际 GitHub 限制是 100MB——意思是给编译后的 bundle 预留空间。

哪些项目最容易撞这个墙

解决方案

方案一：本地打包（最简单）

如果你的 dist 里存在超过 100MB 的文件——直接改走本地打包：

• 不走 GitHub → 不 push 到仓库 → 完全绕开 GitHub 限制
• PakePlus 本地打包对文件大小没有限制
• 缺点：只能出当前系统一个平台（如果需要多平台就得各系统本地打包）

适合：Unity/Cocos 大项目、只出当前系统包的场景。

方案二：Git LFS（云端 + 不拆分）

GitHub 提供了 Large File Storage（LFS）功能，专门处理大文件。安装后，超过阈值的文件会被 LFS 自动跟踪。

步骤

# 1. 安装 Git LFS（如果还没装）
git lfs install

# 2. 在 PakePlus fork 仓库里设置 LFS 跟踪规则
cd 你的-fork-仓库
git lfs track "*.data" "*.wasm" "*.mp4" "*.glb"
git add .gitattributes
git commit -m "Track large files with LFS"
git push

之后 PakePlus 推送 dist 时，这些大文件会自动走 LFS 通道而不是普通 Git 通道。

LFS 的限制

• 免费额度：GitHub 免费用户有 1GB LFS 存储 + 1GB/月下载流量
• 超额：超出后下载会被节流，需要付费（$5/月起）
• Release Asset 还是 2GB 限制：LFS 只管仓库存储，不管 Release 上传

方案三：大资源走外部 CDN

把大资源（视频、音频、图集、字体）放到外部对象存储（阿里云 OSS、腾讯云 COS、AWS S3），让打包后的 APP 运行时从外部加载。

做法

1. 把大文件上传到对象存储
2. 在你的前端代码里（Vue/React/Cocos/Unity）改资源加载路径，指向 CDN URL
3. PakePlus 只打包小文件（HTML + 少量 JS/CSS）
4. APP 运行时，大资源从 CDN 拉取

适用场景

• 视频站（视频文件走 CDN）
• 游戏资源热更新（把大图集放 CDN）
• 字体丰富的文档编辑器（字体放 CDN）

注意

PakePlus WebView 里跨域加载 CDN 资源需要 CORS 配置——确保对象存储的 CORS 规则允许你的源域名或 *。

方案四：资源拆分 / 压缩

压缩完再看是否降到 GitHub 限制以下。

Release 上传的 2GB 限制

如果用本地打包出了一个 3GB 的绿色版 zip，想上传到 GitHub Release 也会被拒。

解决：

• 用对象存储托管大产物
• 分卷压缩后再上传
• 改走本地分发（网盘、IM 直接发）

PakePlus 本身的处理

PakePlus 文档里的"文件大小限制"和"文件数量限制"是 PakePlusApi 里显示的配额——这些是 PakePlus 层面的软限制，不是 GitHub 的硬限制。实际 push 到 GitHub 时还是会撞到 GitHub 100MB 的墙。

总结