--prefer-dist仍git clone的根本原因是dist包不可用，Composer自动静默fallback；需验证-v输出含Downloading archive、vendor无.git、composer show -s显示非空dist URL才确认生效。
加了 --prefer-dist 为什么还在 git clone？
根本原因不是参数没写，而是 Composer 没找到可用的 dist 包——它会静默 fallback 到 source，你看到 Cloning into 'vendor/xxx' 就是 fallback 的结果。
- 包没打 tag（比如只有
dev-main），Packagist 就不生成dist.url -
composer.json里写了"preferred-install": {"*": "source"}，直接覆盖命令行参数 - 环境变量
COMPOSER_PREFER_SOURCE=1已设置，优先级高于--prefer-dist - 私有 GitLab 仓库没开 archive 功能，或
composer.json的dist字段缺失/URL 404
怎么确认 --prefer-dist 真生效了？
不能只看命令里有没有这个参数，得验证行为：
- 加
-v运行：composer install -v，输出中必须出现Downloading https://.../archive/...（含tarball、zipball或archive字样），且**没有**Cloning或git clone - 检查
vendor/some/package/目录：里面**没有**.git文件夹 - 运行
composer show vendor/package -s：输出中dist字段非空，含url和sha256
镜像源配置错误会让 --prefer-dist 失效
国内镜像（如阿里云）若同步延迟或元数据不全，dist.url 可能指向 404，Composer 自动退到 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
CI 构建里怎么安全用 --prefer-dist？
单加参数没用，必须组合三件事：
- 先确保全局镜像已切对：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 清掉旧缓存：
composer clear-cache（尤其换过镜像后，混用协议会导致失败） - CI 命令推荐组合：
composer install --prefer-dist --no-dev --optimize-autoloader --no-interaction - 缓存
~/.composer/cache目录，仅当composer.lock变化时才重装
如果 Docker 镜像（如 php:alpine）没装 git，别急着 apk add git —— 那只是掩盖问题，不如直接确认 --prefer-dist 是否真走通。
