Composer镜像配置总不生效是因为必须同时满足三个硬性条件：键名必须为单数repo.packagist、第二个参数必须显式写composer（type值）、URL必须HTTPS且末尾带/；任一缺失即静默回退官方源，验证需输出完整JSON对象。
在 Docker 容器里配 Composer 镜像源，不是“设了就生效”，而是必须满足三个硬性条件：键名 repo.packagist（单数）、composer 作为 type 值、URL 必须是 HTTPS 且末尾带 /；漏掉任意一个，composer install 就会静默回退到 packagist.org，卡在 Resolving packages...。
为什么 composer config -g repo.packagist 总不生效
它不是报错失败，而是根本没写进去——Composer 2.2+ 对格式极其严格：
-
repo.packagist是唯一合法键名，写成repos.packagist或packagist.org全部无效 - 第二个参数必须显式写
composer，它是 type 值，不是注释，不能省略或替换 - URL 必须以
https://开头，且结尾必须有/，例如https://mirrors.aliyun.com/composer/；少斜杠会导致请求/composerpackages.json，404 后直接 fallback - 验证是否成功：运行
composer config -g repo.packagist，输出必须是完整 JSON，如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}；空、null、或只返回 URL 字符串，都说明失败
Alpine 镜像中 HTTPS 请求失败的常见原因
用 php:alpine 构建时，即使镜像源配置正确，composer install 仍可能报 SSL certificate problem：
- Alpine 默认不带 CA 证书，必须显式安装：
RUN apk add --no-cache ca-certificates - 部分 Alpine 镜像（如
composer:2）还缺curl，导致composer config静默失败，建议补上：RUN apk add --no-cache curl - 别用已停用的旧地址，如
https://packagist.phpcomposer.com，换成https://mirrors.aliyun.com/composer/ - 如果构建阶段用了
--no-cache，但配置命令被缓存层跳过，也要检查是否在COPY composer.json composer.lock ./之后才执行composer config，否则项目级repositories字段会覆盖全局配置
多阶段构建中 final 阶段镜像源失效
builder 阶段明明配好了，final 阶段一运行 composer dump-autoload 又连回 packagist.org，问题通常出在三处：
-
composer config -g写入的是/root/.composer/config.json，而 final 阶段若以www-data用户运行，它读不到 root 的配置；解决方法是切换用户执行：RUN su www-data -c "composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/" - builder 和 final 阶段 PHP 版本/发行版不一致（比如 builder 用
php:8.2-cli-bullseye，final 用php:8.2-fpm-alpine），会导致 autoload classmap 路径错乱，间接触发依赖重解析 - final 阶段未预装必要扩展（如
mbstring、zip），composer install被迫降级为update行为，重新解析时忽略全局源；务必在 final 阶段也确保扩展就绪
项目级配置比全局更可靠，尤其在 CI 和协作场景
全局配置（-g）只对当前用户生效，CI 流水线、宝塔、Docker 容器默认不读它；团队协作应优先走项目级：
- 进项目根目录（含
composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意不加-g） - 该命令会向
composer.json的repositories字段追加条目，不破坏已有私有源；但前提是"repositories": {}（对象格式），若为数组[]会报错，需先手动改格式 - 改完必须删掉
vendor/和composer.lock，再跑composer install（不是update），否则lock文件仍记录旧源的 dist URL - 一旦
composer.json里有repositories，它就完全屏蔽全局配置——这不是 bug，是设计，意味着你得把镜像源当成项目契约的一部分来维护
最易被忽略的点是：换源后不清理缓存和 composer.lock，就等于白配；哪怕命令输出看起来成功，只要日志里还出现 packagist.org，就说明旧元数据仍在驱动解析流程。
