大文件处理

当你通过 Git 在 Zeabur 上部署项目时，你的仓库会被下载并作为构建上下文使用。仓库中的大文件（如二进制文件、数据集、媒体文件或机器学习模型）会显著增加构建时间，甚至可能导致构建失败。

本指南说明大文件为何会造成问题，以及如何处理它们。

为什么大文件会造成问题

构建上下文大小限制

从 GitHub 部署时，Zeabur 会将你的仓库下载为 ZIP 压缩包。此压缩包有 1 GiB 的大小限制 — 如果你的仓库超过此限制，构建将会失败。即使在此限制以下，较大的仓库也会因为下载和解压时间增加而导致构建速度变慢。

不支持 Git LFS

如果你的仓库使用了 Git LFS，构建服务器只会收到 LFS 指针文件，而不是实际的文件内容。你需要将这些文件移至外部存储方案。

容器镜像大小

包含在最终容器镜像中的大文件会增加部署、扩展和重启服务所需的时间。保持镜像精简可确保更快的冷启动和更高效的资源使用。

建议做法

从仓库中移除大文件

由于 Zeabur 会下载整个仓库进行构建，大文件无法通过 .dockerignore 或类似机制排除。你应该直接从仓库中移除大文件。

使用 .gitignore 防止大文件被提交：

# 数据集和大型媒体文件
*.csv
*.parquet
data/
assets/videos/

# 构建产物
dist/
*.log

# 机器学习模型
*.bin
*.h5
*.onnx

使用外部对象存储存放大型资源

对于大型静态资源（如图片、视频或机器学习模型），请将它们存储在外部对象存储服务中（例如 AWS S3、Cloudflare R2 或任何 S3 兼容的服务），并在应用程序中通过 URL 引用它们。

这样可以保持仓库和容器镜像的精简，同时让你的应用程序在运行时能访问所需的文件。

使用 Volumes 存放运行时数据

如果你的应用程序在运行时会生成或需要大文件（如用户上传的文件、缓存文件或数据库），请使用持久化存储，而不是将它们包含在容器镜像中。

存储在 Volumes 中的文件会在部署和服务重启之间持续保留，且不会影响你的构建上下文大小。

保持仓库精简

遵循以下一般最佳实践来保持仓库的精简：

• 不要提交二进制文件 — 编译后的文件、可执行文件和压缩包应在 CI 中构建或在运行时下载。
• 使用 .gitignore — 排除构建产物、依赖包（node_modules、venv）和临时文件。
• 拆分大型仓库 — 如果你的仓库包含多个独立服务，考虑将它们拆分为独立的仓库，并使用监控路径或根目录来管理部署。