直接在运行镜像中执行composer install不可靠：php扩展缺失、工具缺失或php版本不匹配（如builder用8.2而final用8.1）会导致构建成功但运行时报错；正确做法是多阶段构建，builder与final严格使用相同php版本，按composer.json/lock→install→代码顺序copy，并显式统一workdir和权限。
直接在运行镜像里执行 composer install 是错的——不是“不推荐”，而是根本不可靠：PHP 扩展缺失、git/unzip 缺失、ext-mbstring 没启用，都会让安装中途失败；更隐蔽的问题是，composer.lock 里记录的包版本可能依赖 PHP 8.2+ 语法，但你的运行镜像用的是 PHP 8.1，结果构建成功、运行时报 ParseError: unexpected token "readonly"。
builder 阶段必须和 final 镜像 PHP 版本完全一致
常见错误是用 composer:2 或 php:8.2-cli 当 builder，却用 php:8.1-apache 当 final。这会导致两类问题：
-
composer install在 builder 中成功，但生成的autoload_classmap.php引用了 PHP 8.2 特有语法，运行时直接 fatal error - 某些包（如
symfony/flex）的 post-install-cmd 脚本会检查phpversion()，版本不匹配就跳过关键初始化
正确写法：
FROM php:8.1-cli-bullseye AS composer_build
而不是 FROM composer:2 或 FROM php:8.2-cli。版本号必须一字不差对齐 final 阶段所用的 FROM 行。
COPY 顺序错了，缓存就全废了
Docker 层缓存只认文件内容哈希，且严格按顺序生效。只要中间插了一行无关指令，后续所有层都失效。
典型错误写法：
COPY . /app<br>RUN chmod +x /app/scripts/init.sh<br>COPY composer.json composer.lock ./<br>RUN composer install --no-dev --optimize-autoloader
这会让每次改代码都重跑 composer install，因为 COPY . /app 已经破坏了缓存链。
必须严格按这个顺序：
-
COPY composer.json composer.lock ./（最早、最稳） RUN composer install --no-dev --optimize-autoloader --classmap-authoritative-
COPY . .（最后，不影响 vendor 层）
别在 composer install 前后加任何 RUN，比如 mkdir、chown、apt-get update —— 这些必须放在 COPY 之前，或挪到 final 阶段。
COPY --from=builder 的路径和权限陷阱
现象：require(): Failed opening required 'vendor/autoload.php'，但 ls -l /app/vendor/autoload.php 显示文件存在。
原因往往有两个：
-
WORKDIR不一致：builder 设的是/app，final 设的是/var/www/html，那么COPY --from=builder /app/vendor /app/vendor实际复制到了/var/www/html/app/vendor，而 autoloader 里硬编码的路径仍是/app/vendor - 权限问题：Alpine 镜像默认以
root运行，但pdo_mysql等扩展加载时会校验vendor/下某些文件属主；PHP-FPM 容器若以www-data启动，就会拒绝读取root:root的autoload_static.php
解决方法：
- 两个阶段都显式声明：
WORKDIR /app - final 阶段加一句：
RUN chown -R www-data:www-data /app/vendor - 别用
COPY --from=builder /app /app，只复制必要目录：COPY --from=builder /app/vendor /app/vendor
--ignore-platform-reqs 是毒药，别乱用
它确实能让 composer install 在低内存或错版本 PHP 下“跑通”，但代价是掩盖真实环境不一致。例如：
- builder 是 PHP 8.2，锁文件里装了
spatie/laravel-rayv1.32（要求php >=8.2） - final 是 PHP 8.1，加了
--ignore-platform-reqs强行装上，但运行时调用Ray::color()就抛出Fatal error: Typed property must not be accessed before initialization
真正该做的是：
- 在 CI 中校验
composer.json的config.platform.php字段是否与目标镜像版本一致 - 本地开发用
docker run --rm -v $(pwd):/app -w /app php:8.1-cli composer install提前暴露问题 - 把
--ignore-platform-reqs当作临时调试开关，绝不能进主干 Dockerfile
多阶段构建本身不难，难的是 builder 和 final 之间那几行看似无害的路径、权限、版本、缓存链——它们不出错时悄无声息，一出错就是容器启动即崩，且日志里找不到直接线索。
