Composer config repo.packagist命令不生效是因为三要素必须全对：键名必须为单数repo.packagist、第二参数必须显式写composer、URL必须以/结尾，任一缺失均静默回退官方源且不报错。
composer config repo.packagist 命令为什么总不生效
它不是“改个地址就完事”，而是三要素全对才写入有效配置：键名必须是 repo.packagist（单数，不能多 s），第二个参数必须是 composer（声明仓库类型），URL 必须以 https:// 开头且末尾带 /。漏掉任意一项，composer config -g repo.packagist 查出来就是空或 null，但命令本身不报错，你根本不知道配错了。
-
composer config -g repos.packagist ...→ 多一个s，字段存进去了，Composer 2.x+ 完全忽略 -
composer config -g repo.packagist https://mirrors.aliyun.com/composer/→ 缺composer类型声明，新版直接 fallback 到packagist.org -
https://mirrors.aliyun.com/composer→ 少末尾/，请求路径拼成/composerpackages.json，404 后静默回退
本地开发用项目级镜像比全局配置更稳
你在终端用 root 配了全局镜像，但 PhpStorm、VS Code 终端、或宝塔后台部署时实际运行的是 www 用户，它读不到 root 的 ~/.composer/config.json。项目级配置把镜像写进 composer.json，提交 Git 后所有人行为一致，CI 脚本也不用操心用户权限。
- 进项目根目录执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意没-g） - 该命令只向
composer.json的repositories对象里追加"packagist"字段，不覆盖已有私有源——前提是原repositories是对象（{}），不是数组（[]） - 如果
composer.json里已有"repositories": []，命令会失败；需先手动改成"repositories": {} - 别手写
"packagist.org": false，这会彻底关掉默认源，镜像临时不可用时composer install直接失败
换镜像后 vendor 还是拉旧包？删 lock 和 vendor 再来
镜像只影响元数据（packages.json）解析和 ZIP 下载地址，但 composer.lock 里存的是旧的哈希和 dist URL。不清理就重装，Composer 会按 lock 文件里的记录去拉包，哪怕镜像已生效，也可能因路径不匹配或校验失败卡住。
- 执行前先删掉：
rm -rf vendor composer.lock - 再跑：
composer install --no-dev --prefer-dist - 如果项目依赖私有 Git 仓库，确保
dist.url字段在 lock 文件里是相对路径（如./artifacts/pkg-1.2.3.zip）或file://协议，否则 artifact 源无法命中
Docker 或 CI 中镜像失效的真实原因
不是镜像地址不行，是你配的配置没落到真正执行命令的用户上下文里。Docker 构建阶段默认用 root，但有些基础镜像（如 php:8.3-apache）会在最后切到 www-data；GitHub Actions 默认用 runner 用户；宝塔后台部署用 www 用户。它们各自读各自的 ~/.composer/config.json。
- CI 脚本里别依赖全局配置，改用临时环境变量更可靠：
COMPOSER_MEMORY_LIMIT=-1 php -d xdebug.mode=off $(which composer) install --no-dev --prefer-dist - Dockerfile 中显式指定用户并重配：
RUN sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 验证是否生效：在构建阶段插入
composer config -g repo.packagist，输出必须是完整 JSON，不能是null或空行
镜像配置最脆弱的地方不在 URL 本身，而在 repo.packagist 这个键名和 composer 这个 type 值——它们是 Composer 2.2+ 硬编码识别的开关，写错一个字符，整个加速逻辑就形同虚设，还不会给你任何提示。
