项目级配置比全局配置更适合团队协作，因其将镜像写入composer.json并提交Git，确保所有成员和CI环境行为一致；全局配置因用户权限、本地差异易导致vendor和lock文件不一致。
项目级配置比全局配置更适合团队协作
全局配置（composer config -g）写在 ~/.composer/config.json 里，每个开发者本地环境不同，有人配了阿里云，有人没配，CI 流水线用的是 runner 用户，根本读不到 root 的配置——结果就是 composer install 在不同机器上行为不一致，vendor 目录差异、lock 文件哈希不匹配、甚至某些包拉不到。
项目级配置把镜像地址写进 composer.json 的 repositories 字段，提交到 Git，所有人 clone 后直接生效，无需额外操作。命令很简单：
- 进项目根目录（确保有
composer.json） - 运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/ - 检查
composer.json是否新增了"repositories": {"packagist": {...}}结构
注意：如果项目已有 "repositories": []（数组格式），命令会失败；必须先改成 "repositories": {}（空对象）再执行。
别关掉 packagist.org 回退机制
很多团队为“彻底锁定源”在 repositories 里加 "packagist.org": false，这反而埋雷：一旦镜像同步延迟（比如新发布的包还没入库），composer install 直接报错 Package not found，没人能装得通。
Composer 2.2+ 默认开启自动 fallback——镜像返回 404 或 503 时，会悄悄切回官方源查一次。这个保险丝不该手动剪断。正确做法是保留镜像条目，但不显式禁用官方源：
- ✅ 正确：
"repositories": {"packagist": {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}} - ❌ 错误：
"repositories": [{"packagist.org": false}, {"packagist": {...}}]（顺序错 + 显式关闭）
验证方式：删掉 vendor 和 composer.lock，跑 composer install -vvv 2>&1 | grep "Downloading"，看到 mirrors.aliyun.com 就是主路径，偶尔出现 packagist.org 是 fallback 触发，属正常。
CI/CD 中必须清理旧缓存并强制重装
CI 环境（如 GitHub Actions、GitLab CI）通常复用缓存的 vendor 或 composer.lock，但镜像切换后，旧 lock 文件里的包哈希可能和新镜像元数据不一致，导致安装中途失败或降级。
CI 脚本里不能只写 composer install，要加这几步：
-
composer clear-cache（清掉本地缓存，避免混用旧镜像缓存） -
rm -rf vendor composer.lock（彻底清除状态） -
composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction（带优化参数，且不交互）
特别注意：--classmap-authoritative 不适合 CI 构建阶段启用——它依赖完整类映射，而 CI 往往只装 production 依赖，缺少 dev 类，会导致后续测试阶段 Class not found。
宝塔、Docker 等多用户环境别碰全局配置
宝塔面板后台执行部署脚本时，默认以 www 用户运行；Docker 容器里常指定非 root 用户（如 php:8.3-cli 镜像默认用 www-data）。你在终端用 root 执行的 composer config -g，它们根本看不到。
此时硬配全局等于白配。解决路径只有两条：
- 切到对应用户下配：例如宝塔里执行
sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 更推荐：放弃全局，直接走项目级配置 +
COMPOSER_REPO_PACKAGIST环境变量注入（CI 中常用）
环境变量方式更干净：COMPOSER_REPO_PACKAGIST=https://mirrors.aliyun.com/composer/ composer install，不改任何文件，且优先级高于全局配置，适合容器化部署。
多人协作里最麻烦的不是配错镜像，而是有人手动改了 composer.json 的 repositories 却没提交，或者本地用了 --repository-url 临时参数但忘了删——这些都会让别人 checkout 后 install 失败。统一靠 Git 提交的项目级配置，才是真·统一。
