最核心方案是多阶段构建+严格分层缓存+非root运行；因生产镜像缺git/zip等依赖、宿主机环境不一致易致class not found或权限错误，且违反最小权限原则。
构建阶段必须用 composer install，而不是 composer update
容器镜像要可重现、可部署，依赖就必须锁定在 composer.lock 上。一旦在 RUN 指令里跑 composer update，就会改写 composer.lock，而该文件通常由 Git 管控——容器里改了也提交不了，下次构建又回退，等于白干。
真正需要升级依赖时，应该在宿主机上运行 composer update，提交新的 composer.lock，再触发镜像重建。
-
composer install会严格按composer.lock安装，保证结果一致 -
composer update必须配合--dry-run仅用于 CI 兼容性验证，且禁止写入挂载的 lock 文件 - 若
composer.lock不存在，composer install会自动降级为update，结果不可控——务必确保它在构建上下文中
COPY 顺序错了，缓存就全废了
Docker 构建缓存是逐层生效的。如果把 COPY . /app 放在 composer install 前面，哪怕只改了一个空格，整个 vendor 安装层都会失效，每次重下全部包。
正确顺序必须是：先复制 composer.json 和 composer.lock，立刻执行安装，最后才复制其余代码。
COPY composer.json composer.lock ./RUN composer install --no-dev --optimize-autoloader --no-progress --no-interaction-
COPY . .（注意：不是COPY . /app，避免覆盖已安装的 vendor）
国内网络环境下不设镜像源，composer install 几乎必卡
默认直连 packagist.org 在国内基本超时，错误常表现为 file could not be downloaded: failed to open stream: Connection timed out 或卡在 “Downloading” 状态超过 5 分钟。
别依赖全局配置或宿主机设置——构建过程不复用 ~/.composer/cache，也不读宿主机的 auth.json 或镜像配置。
- 在
RUN指令中显式设置：RUN COMPOSER_REPO_PACKAGIST=https://mirrors.aliyun.com/composer/ composer install ... - 或者用
composer config -g写入全局配置（但要注意 Alpine 镜像需先装证书：RUN apk add --no-cache ca-certificates） - 避免使用已停用的镜像源，如
https://packagist.phpcomposer.com；推荐阿里云或华为云代理源
多阶段构建 + BuildKit 缓存才是生产级做法
单阶段镜像会把 Composer、PHP 开发扩展、临时文件全打包进去，体积大、启动慢、有安全风险。多阶段构建能彻底剥离这些，只保留运行必需的 vendor/ 和代码。
BuildKit 的 --mount=type=cache 能让多次构建复用 /root/.composer/cache，大幅减少重复下载。
- 第一阶段用完整 PHP 镜像（含
curl、zip、openssl），安装 Composer 并执行composer install - 第二阶段用
php:8.3-cli-alpine或php:8.3-apache-slim，只COPY --from=0 /app/vendor /app/vendor - 启用 BuildKit：
DOCKER_BUILDKIT=1 docker build .，并在 Dockerfile 开头加# syntax=docker/dockerfile:1 - 缓存挂载写法：
RUN --mount=type=cache,target=/root/.composer/cache composer install ...
最容易被忽略的是 PHP 版本和扩展一致性：宿主机用 PHP 8.2 跑 update，但容器是 8.1，composer.lock 可能记录了不兼容版本，构建时报 Your requirements could not be resolved。
