宿主机的composer config对容器无效，因为Docker构建使用全新环境，~/.composer/config.json不存在；必须在Dockerfile中用RUN composer config -g显式配置镜像源，并确保Alpine先安装ca-certificates，同时严格按顺序COPY composer.lock和composer.json以利用缓存。
为什么宿主机的 composer config 对容器无效
因为 Docker 构建时是全新环境，~/.composer/config.json 不存在，宿主机上执行的 composer config -g 完全不生效。你看到的“配置已设”只是骗自己——构建阶段根本读不到。
必须在 Dockerfile 中显式注入配置，否则所有请求仍发往 packagist.org，国内环境下大概率卡在 Resolving packages... 或报 Curl error: SSL certificate problem。
- Alpine 镜像需先装证书：
RUN apk add --no-cache ca-certificates - 设置镜像源用
RUN composer config -g repo.packagist https://mirrors.aliyun.com/composer/（注意末尾不要加composer） - 别用
COMPOSER_REPO_PACKAGIST环境变量替代——它只对单条命令生效，后续composer require还会回退
如何让 composer install 不卡住、不超时
不是 Composer 慢，是它在等 packagist.org 响应。即使你设了镜像源，也可能被其他配置覆盖或因缓存顺序错乱导致退化为 update 行为。
-
COPY必须严格按顺序：先COPY composer.lock .，再COPY composer.json .，最后RUN composer install - 加
--no-interaction -vvv 2>&1 | grep "Downloading"验证是否真走阿里云源 - 避免在
RUN composer install前COPY . /app——改一行代码就重装整个vendor，CI 构建从 40 秒飙到 6 分钟很常见
多阶段构建中 PHP 版本错配会直接运行时报错
不是“可能出问题”，而是必然失败。比如 composer.lock 记录了依赖 PHP 8.2 的 readonly 语法，但 final 镜像用的是 PHP 8.1，构建成功，启动时直接 Fatal error: Uncaught ParseError。
- builder 阶段和 final 阶段的 PHP 小版本（如
8.1）、发行版（如bullseye或alpine3.19）必须一字不差对齐 - 别图省事用
FROM composer:2 AS builder——它绑定的 PHP 版本不可控，且不一定启用ext-mbstring、ext-xml等必需扩展 - final 阶段
COPY --from=builder /app/vendor /app/vendor时，要确保WORKDIR和权限匹配，否则运行时报Failed opening required 'vendor/autoload.php'
权限和用户 UID 不一致会导致 vendor 不可写
宿主机项目目录属 root，挂载进容器后，非 root 用户（如 UID 1001）无法写入 vendor/；哪怕构建成功，运行时自动加载也会失败。
- 提前在宿主机运行：
chown -R 1001:1001 ./project - 若用
-v $(pwd):/app挂载，Docker for Mac 推荐加:delegated，Podman 加:z - 基础镜像若默认用
www-data用户，构建前加USER www-data，并确保该用户对/app有写权限
最易被忽略的点是：builder 和 final 镜像的 PHP 发行版（比如 alpine3.19 vs alpine3.20）哪怕只差一个小版本，也可能导致 ext-zip 编译行为不同，最终 autoload classmap 生成异常——这种问题不会在构建时报错，只会在请求第一个路由时静默崩溃。
