Composer中文环境下针对Git-LFS大文件依赖的下载优化实战-composer-PHP中文网

composer本身不处理git lfs下载，所有lfs失败问题根源在git环境或ci/cd流程：git未激活lfs导致vendor中全是指针文件，需手动在各vendor子目录执行git lfs pull，且composer镜像、缓存等机制对lfs无影响。

composer中文环境下针对git-lfs大文件依赖的下载优化实战

Composer 本身不处理 Git LFS 文件下载，所有“LFS 大文件下载失败”问题，根源都在 Git 环境或 CI/CD 流程里，不是改 composer.json 或调 composer install 参数能解决的。

Git LFS 未激活导致 vendor 里全是指针文本

执行 composer install 后进入 vendor/some/package，打开本该是二进制的文件（如 model.bin），内容却是：

version https://git-lfs.com/spec/v1
oid sha256:abc123
size 104857600

这说明 Git 没有触发 LFS 下载逻辑，只是把指针文件原样检出了。常见原因和检查项：

git lfs install 是否在当前用户环境成功运行？必须看到 Updated git hooks 输出才算生效
git config --get filter.lfs.process 返回值是否为 git-lfs filter-process？不是则 LFS 过滤器未注册
目标包仓库根目录下是否存在 .gitattributes，且含类似 model.bin filter=lfs 的行？没有就无法识别大文件
CI/CD 中（如 GitHub Actions）是否用了 actions/checkout@v4？它默认不拉 LFS，必须显式加一步：run: git lfs pull

Composer 安装时如何让 Git LFS 生效

Composer 调用的是 git clone 和 git checkout，它完全不解析 .gitattributes，也不执行 git lfs pull。这意味着：

不能在 composer.json 的 scripts 里写 "post-install-cmd": "git lfs pull" —— 因为 git lfs pull 必须在每个 vendor 子包自己的 Git 仓库目录下执行，而 Composer 不会自动 cd 进去
composer update 过程中不会重跑 git lfs install，哪怕你本地根本没装 LFS，它也照常 clone，只留下一堆指针
真正可行的做法：在项目根目录执行完 composer install 后，手动遍历 vendor 中含 .git 的子目录，逐个执行 git lfs pull

一个轻量脚本示例（Linux/macOS）：

Lovefromio Github

使用 `gh` CLI 与 GitHub 交互。通过`gh issue`、`gh pr`、`gh run` 和 `gh api` 管理 issue、PR、CI 运行以及高级查询。

下载

find vendor -name ".git" -type d -exec dirname {} \; | while read dir; do
  [ -f "$dir/.gitattributes" ] && (cd "$dir" && git lfs pull 2>/dev/null || true)
done

中文网络环境下加速 Git LFS 下载的关键配置

国内直连 GitHub LFS endpoint（https://github.com/.../lfs）常因 TLS 握手慢、连接超时失败。需组合调整 Git 全局配置：

git config --global lfs.concurrenttransfers 8 —— 提升并发数（默认仅 3），充分利用带宽
git config --global lfs.dialtimeout 15 —— 缩短连接建立超时，避免卡死
git config --global lfs.httptimeout 600 —— 延长单个大文件 HTTP 请求超时（尤其 >500MB）
git config --global http.postBuffer 524288000 —— 设为 500MB，防止上传/下载中途被 Git 自身缓冲区截断
若使用代理或企业内网，可配 git config --global lfs.url "https://your-lfs-proxy.example.com/objects" 指向内部缓存节点

为什么不能靠 Composer 缓存或镜像解决 LFS 问题

Composer 的 cache-dir、镜像源（如阿里云 https://mirrors.aliyun.com/composer/）、--prefer-dist 等机制，全部作用于 Packagist 分发的 ZIP 包。而 Git LFS 是 Git 协议层的扩展，它的文件走的是独立的 LFS API endpoint，和 Composer 的下载路径完全隔离。

换句话说：你给 Composer 配再快的镜像，对 git lfs pull 从 GitHub LFS 下载 model.bin 这件事，0 影响。唯一能动的，只有 Git 和 LFS 本身的配置与环境。

最容易被忽略的一点：很多团队在 Docker 构建中用 git clone 拉主项目，却忘了在构建阶段 RUN git lfs install && git lfs pull —— 结果镜像里 vendor 下全是文本指针，运行时报 file not found 或内容损坏。