必须在Docker构建阶段显式配置镜像源，否则默认直连packagist.org被防火墙拦截；常见错误包括宿主机配置不继承、项目级repositories未禁用官方源（需加"packagist": false）、Alpine镜像缺失ca-certificates导致SSL失败。
构建阶段的 Composer 镜像源配置必须显式生效，否则会默认直连 packagist.org —— 这在多数企业网络或 CI 环境中直接被防火墙拦截，表现为超时、SSL handshake failed 或 503 错误，本质是“网络逃逸”而非网络慢。
为什么 RUN composer install 会绕过你设的镜像源
常见错误是只在宿主机配了全局镜像源（composer config -g），但 Docker 构建完全不继承宿主机的 ~/.composer/config.json；或者只在 composer.json 里写了 "repositories"，却没加 "packagist": false，导致 Packagist 官方源仍被隐式启用，触发回源请求。
- 必须在
RUN指令中显式设置环境变量：RUN COMPOSER_REPO_PACKAGIST=https://mirrors.aliyun.com/composer/ composer install - 或在构建时写入全局配置：
RUN composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/ - 若项目
composer.json中自定义了repositories，务必加上"packagist": false，否则 Packagist 仍会作为 fallback 被访问 - 验证是否生效：在
RUN后加一句composer config --global repo.packagist，输出应为你的镜像 URL，而非https://packagist.org
Alpine 镜像下 SSL certificate problem 的真实原因
不是证书过期，而是 Alpine 默认不带 CA 根证书包，curl 和 PHP 的 openssl 扩展都无法校验 HTTPS 域名证书。即使你用了镜像源，只要 URL 是 HTTPS（阿里云镜像就是），就会卡在 SSL 握手。
- 必须在
RUN前安装证书：RUN apk add --no-cache ca-certificates - 别用
apk add --update，它会触发索引更新，在离线或受限网络中失败 - 如果还报错，检查是否用了
php:alpine但没装openssl扩展：RUN docker-php-ext-install openssl（部分精简镜像需手动启用）
Docker BuildKit 下的 --secret 与私有源认证隔离
当项目依赖私有 Git 仓库或 Artifactory，把 auth.json COPY 进镜像等于泄露凭证。BuildKit 的 --secret 是唯一安全方式，但容易漏掉关键细节。
- 在
Dockerfile中用RUN --mount=type=secret,id=composer_auth composer install - 构建时传入：
docker build --secret id=composer_auth,src=~/.composer/auth.json . - 必须在
RUN内部用composer config --auth加载 secret 文件，不能靠 COPY 或环境变量 - 注意：secret 默认挂载路径是
/run/secrets/composer_auth，composer install不会自动读取，得手动composer config --auth http-basic.example.com ...或用脚本解析
最容易被忽略的是：即使所有镜像源都配对了，只要 composer.lock 里某个包的 dist.url 是原始 GitHub/GitLab 地址（未走镜像），composer install --prefer-dist 仍会尝试直连——此时需确保镜像源支持 dist 重写（阿里云镜像支持），或强制 --prefer-source 并配合 git 工具和 SSH agent forwarding（更复杂）。
