如何设置Composer下载依赖包的具体下载策略？

本文共计1181个文字，预计阅读时间需要5分钟。

Composer默认会检查本地缓存是否有对应版本的包，如果没有，会尝试下载对应的dist包。但前提是它能够确认该包的dist.url有效且未被修改。一旦本地缓存失效或路径不匹配，就会回退到从网络上下载。

确保缓存命中的关键操作：

• 始终使用 --prefer-dist（默认行为，但显式加上更稳妥），避免触发 source 克隆逻辑
• 不要手动删掉 COMPOSER_HOME/cache/ 下的 archival/ 或 repo/ 子目录——它们各自承担不同职责，误删会导致“缓存存在却不用”的现象
• 运行 composer install -v 观察日志：看到 Loading from cache 才算真正命中；若出现 Downloading ...，说明缓存没起作用
• 私有包必须提前在 composer.json 的 repositories 中正确定义，否则 Composer 根本不会把它的 dist 包存进缓存

如何强制所有依赖都用 zip 包安装（跳过 git clone）

有些包在 composer.lock 里记录的是 source 类型（比如你本地开发时用了 --prefer-source，或包本身没提供 dist），这会导致离线或 CI 环境下因缺 Git 而失败。

解决方法不是改 lock 文件，而是从源头控制安装方式：

• 执行 composer install --prefer-dist --no-dev --optimize-autoloader，三者缺一不可：--prefer-dist 强制走归档包，--no-dev 减少非必需包干扰，--optimize-autoloader 附带验证 autoload 是否可用
• 检查单个包类型：运行 composer show vendor/package，看输出中 type 是 library 还是 project，再确认 dist 段是否存在且 url 非空
• 若某包只有 source，需联系维护者补全 dist 发布，或在自己 fork 的 composer.json 中手动补上 dist 字段（含 url 和 shasum）

镜像源配置错误导致下载策略失效

你以为切了阿里云镜像就万事大吉？不一定。Composer 的下载策略高度依赖镜像源返回的元数据完整性。如果镜像同步延迟或丢包，dist.url 可能指向 404，结果就是 fallback 到 source 或直接报错。

排查和修复步骤：

• 运行 composer config -g repo.packagist 确认当前全局源地址，注意末尾不能有多余斜杠（https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer// ❌）
• 临时切回官方源测试：composer config -g repo.packagist https://packagist.org，如果这时能下，说明镜像有问题
• 某些企业内网镜像不支持 dist 重写，需额外配置 composer config -g repos.packagist.type composer 显式声明类型
• 遇到 Failed to decode response: zlib_decode(): data error，大概率是镜像返回了压缩损坏的 JSON，换源或加 --no-cache 跳过本地解压缓存

自定义 downloader 插件为什么没生效

你写了插件、注册了 ZipDownloader、也调用了 $dm->setDownloader('zip', $yourDownloader)，但日志里完全没你的 log 输出——最可能的原因不是代码错，而是匹配逻辑断在了前面。

真实生效链条比想象中更脆弱：

• 插件类必须实现 Composer\Plugin\PluginInterface，且 composer.json 中 type 必须为 composer-plugin，否则根本不会加载
• dist.type 值必须和你注册的 key 完全一致（如 zip、tar），大小写敏感；若包是 dist.type: "zip"，但你注册的是 'ZIP'，就不会命中
• 如果包没有 dist 段（即 $package->getDistUrl() 返回 null），Downloader 根本不会被调用，此时要干预的是 InstallerInterface
• 调试时别只打 log，加一句 file_put_contents('/tmp/downloader-hit', print_r($package->getName(), true), FILE_APPEND);，确认是不是连包名都没进来

复杂点在于：下载策略不是单一开关，而是由镜像源、cache 状态、lock 文件内容、包自身元数据、插件注册时机共同决定的。哪怕只改一个 dist.url 的协议头（http → https），也可能导致缓存失效或校验失败。