阿里云Composer镜像配置必须严格规范：URL末尾需带斜杠，命令用composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，输出JSON中url字段须含且仅含一个结尾斜杠，type必须为"composer"；项目级配置会清空repositories，需手动编辑composer.json并设"packagist.org": false；已有composer.lock时应删除vendor和composer.lock再重装。
阿里云镜像不是“开了就一定快”，配置错一个字符、漏一个斜杠、或者被项目级配置悄悄覆盖，composer install 就会继续卡在 0 B/s——你根本看不到报错，只觉得“换源没用”。
执行 composer config -g repo.packagist 必须带末尾斜杠
命令必须写成：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
URL 结尾的 / 不是可选的。Composer 2.2+ 版本遇到不带斜杠的地址（如 https://mirrors.aliyun.com/composer）会静默 fallback 到官方源，composer diagnose 仍显示 Repo packagist.org is default，但你完全察觉不到。
- 验证是否写对：运行
composer config -g repo.packagist，输出必须是完整 JSON，形如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} -
url字段值末尾有且仅有一个/；type必须是"composer"，不能是空字符串或"vcs" - 别手写
~/.composer/config.json，容易格式错误；也别用旧键名repos.packagist（少个o），那是 Composer 1.x 的写法，2.0+ 已废弃
项目级配置会直接清空 repositories 字段
进项目根目录后执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g），这条命令不是“追加”，而是全量替换 composer.json 中的 repositories 对象。
- 如果项目原本已配置私有 Git 包源（如
"my-private": {"type": "vcs", "url": "https://git.example.com/pkg"}），执行后整个repositories会被清空，只剩阿里云镜像 - 若需保留原有源，应手动编辑
composer.json，将阿里云镜像作为"packagist"子项写入repositories，并确保"packagist.org": false出现在根节点（非repositories内部） - 检查是否被覆盖：打开
composer.json搜索repositories，或运行composer config -l | grep repositories.packagist
已有 composer.lock 的项目首次用新镜像会 hash 不匹配
旧 composer.lock 文件里记录的是从官方源下载的包哈希和 dist URL，切换镜像后，Composer 仍按原路径去阿里云找 zip 包——但阿里云的 dist 映射路径与官方不同，结果就是校验失败。
- 最稳妥做法：
rm -rf vendor composer.lock，再跑composer install - 不要只删
vendor然后composer install，它会按 lock 文件里的 hash 去镜像找包，而旧 lock 可能指向已下线的 dist URL - 换源后第一次
composer update也可能失败，同样建议先清 lock 和 vendor
宝塔/CI 等环境里全局配置常不生效
composer config -g 写的是当前用户的 ~/.composer/config.json（Linux/macOS）或 C:\Users\用户名\AppData\Roaming\Composer\config.json（Windows）。但在宝塔面板、Jenkins 或 systemd 服务中，实际执行 Composer 命令的用户往往是 www、jenkins 或 root，而非你登录 shell 的用户。
- 排查方法：在宝塔「PHP 管理器」里点「一键部署」前，先用该用户身份执行
composer config -g repo.packagist，看是否输出预期 JSON - CI 脚本中不要依赖全局配置，改用临时参数：
composer install -vvv --repository-url=https://mirrors.aliyun.com/composer/ - 某些脚手架模板（如 Laravel）自带
"repositories": {"packagist.org": false}，本质是禁用 packagist 却没指定替代源，结果就是找不到包——此时得手动补上阿里云镜像配置
