镜像源配置总不生效是因为Composer静默忽略错误配置，必须同时满足三个硬性条件：键名严格为repo.packagist（非repos）、第二个参数必须是composer、URL须以https://开头且末尾带/；验证需运行composer config -g repo.packagist，输出必须是形如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}的完整JSON，否则未写入。
镜像源配置为什么总不生效
不是 Composer 没反应，是它静默忽略错误配置。三个硬性条件缺一不可：repo.packagist（注意不是 repos.packagist）、第二个参数必须是 composer、URL 必须以 https:// 开头且末尾带 /。比如 https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer ❌。
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON，如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。如果为空、null 或仍是 https://packagist.org，说明完全没写进去。
常见踩坑点：
- 在宿主机执行了
composer config -g，但容器里用的是root用户，读的是容器内自己的/root/.composer/config.json，不会继承宿主机配置 - 用了
COMPOSER_REPO_PACKAGIST环境变量——它只影响单次命令，后续composer require仍可能 fallback 到默认源 - Alpine 镜像没装证书：必须先
RUN apk add --no-cache ca-certificates，否则 HTTPS 请求直接报SSL certificate problem
Docker 构建时 vendor 层总不命中缓存
根本不是 Composer 本身的问题，而是 COPY 顺序破坏了 Docker 层依赖链。只要 COPY . . 出现在 RUN composer install 前面，哪怕只改了一个 README.md，整个 vendor 层就会重建。
正确节奏只有一种：
-
COPY composer.json composer.lock ./—— 必须最早、单独、且两个文件已提交进 Git（换行符统一，避免 CRLF/LF 差异导致哈希不一致） -
RUN composer install --no-dev --no-scripts --optimize-autoloader --classmap-authoritative --no-interaction --prefer-dist—— 所有参数都为确定性服务，禁用钩子、跳过 dev 包、生成权威类映射 -
COPY . .—— 放最后；同时确保.dockerignore里有/vendor，防止覆盖已构建好的 vendor 目录
别在 COPY composer.json composer.lock ./ 前加任何 RUN（比如 mkdir 或 chown），除非它绝对稳定、不引入变量。
缓存目录挂载后还是慢？路径和权限要对齐
挂载 ~/.composer-cache 到容器内，只是第一步。真正起效要看三点：路径是否匹配、用户是否有写权限、底层存储是否够快。
查当前生效路径：composer config --global cache-dir，默认是 /root/.composer/cache。Dockerfile 中挂载必须对齐这个路径，比如：
volume: - ~/.composer-cache:/root/.composer/cache
或者在 CI runner 中显式映射：/home/ci-user/.composer/cache → 容器内 /root/.composer/cache。
容易被忽略的细节：
- 缓存目录必须可写，且不能落在机械盘、WSL2 挂载的 Windows 目录、NFS 或加密卷上——I/O 成瓶颈时，install 会慢 2–5 倍
- CI 脚本常以
www或git用户运行，但你用root执行了composer config -g，它们读的是各自家目录下的~/.composer/config.json，配置实际未生效 - BuildKit 的
--mount=type=cache,id=composer-cache,target=/tmp/composer-cache看似高级，但 id 冲突或 PHP 版本不一致时，反而导致依赖解析失败，不如分层 COPY + 锁文件稳定
为什么 composer install 卡在 “Resolving dependencies”
这不是网络慢，是 Composer 在本地暴力穷举满足所有约束的版本组合。尤其当 composer.json 里写了 "*"、"^1.0 || ^2.0" 或 "minimum-stability": "dev" 时，求解器会指数级爆炸。
临时提速手段：
- 删掉
"minimum-stability": "dev"—— 稳定版能砍掉约 80% 的求解时间 - 收紧 PHP 版本约束：
"php": "^8.1"比"php": ">=7.4"少查几百个包的兼容性元数据 - 确认
composer.lock已提交，并始终用composer install（不是update） - 临时禁用 xdebug：
php -d xdebug.mode=off $(which composer) install，它会让解析慢 5–10 倍
更关键的是：别信“换源就快”。如果 composer install -vvv 日志里还出现 packages.json 或 provider-2023 这类路径，说明 Composer 仍在拉取全量元数据——镜像源没配对，或者没关自动元数据更新。
