Composer优先下载压缩包的最有效方式是使用--prefer-dist参数或配置"preferred-install": {"*": "dist"}；若仍报git错误，说明无可用dist包而被迫回退source模式，常见于开发版约束、path类型包或缺失dist字段等情况。
怎么让 Composer 优先下载压缩包（而不是 git clone）
直接加 --prefer-dist 参数，或者在配置里设 "preferred-install": {"*": "dist"}。这是最有效、最可控的方式——它不依赖“包有没有发版”，而是告诉 Composer：“只要能下 zip，就别碰 git”。
实操建议：
- CI/CD 或部署脚本中固定写：
composer install --prefer-dist --no-dev --optimize-autoloader - 想永久生效（全局）：运行
composer config -g preferred-install dist - 只对当前项目生效：运行
composer config preferred-install dist，会写入项目composer.json的config段 - 若只想对某些包走源码（比如本地开发的 SDK），用通配写法：
"preferred-install": {"acme/*": "source", "*": "dist"}
为什么加了 --prefer-dist 还在报 git 错？
不是参数失效，是 Composer 被逼回退到了 source 模式——它找不到可用的压缩包地址，只能硬着头皮去 clone。
常见原因：
- 包用了
dev-main、dev-feature/x这类开发版约束：这类分支通常没发布 dist，Composer 只能 clone - 包是
path类型（比如"../my-local-package"）：这种仓库天生就是 source 模式，--prefer-dist完全无效 - 私有包在
composer.json里写了"type": "git"，但没提供"dist"字段（如url和shasum） -
composer.lock里该包之前是 source 安装的，而你没加--force-reinstall，Composer 就复用旧方式
怎么确认这次真的走了 dist？
别光看命令有没有加参数，得看结果——vendor 目录里有没有 .git 目录，是最直观的判断依据。
验证方法：
- 执行
composer install -v --prefer-dist，输出中出现Downloading https://...（带 zipball 或 releases URL）且没有Cloning git@，说明成功 - 安装完检查
vendor/symfony/console/.git：如果不存在，基本就是 dist；如果存在，说明 fallback 到了 source - 运行
composer show -s symfony/console，看输出里dist字段是否完整（有type、url、shasum）
离线部署时怎么保证 --prefer-dist 不掉链子
离线环境不是加个参数就行，关键在于提前把 dist 包“存进缓存”，并确保 lock 文件里的校验值和缓存内容完全匹配。
必须做的几步：
- 在有网机器上先跑一遍：
composer install --prefer-dist --no-dev（确保所有包都以 dist 方式落地） - 找到缓存目录：
composer config --global cache-dir，通常是~/.composer/cache/files/ - 把整个
files/目录打包，同步到离线机对应路径（注意用户权限一致） - 离线机上运行前，先设环境变量屏蔽网络：
COMPOSER_NO_INTERACTION=1 COMPOSER_CACHE_DIR=/path/to/your/cache composer install
最容易被忽略的一点：如果 composer.lock 是别人生成的，或者在不同网络环境下更新过，里面记录的 dist.shasum 可能和你缓存里的文件不一致——那 Composer 会直接报校验失败，而不是静默跳过。
