必须在Docker构建阶段执行composer install，而非容器启动时或宿主机安装后挂载vendor；否则因PHP扩展缺失、版本错配（如8.2锁文件在8.1运行）、platform未锁定、权限不一致等问题，导致Class not found、ParseError或autoload静默失败。
别在容器启动时跑 composer install，也别在宿主机上装 Composer 后把 vendor/ 挂进容器——这两条路都会导致 Class not found、权限拒绝或镜像不可复现。
为什么不能在 docker run 时执行 composer install
容器启动时的 PHP 环境通常缺 ext-zip、ext-xml、git 或 unzip，composer install 直接报错退出；更隐蔽的问题是：宿主机生成的 composer.lock 基于 PHP 8.2，而容器用的是 PHP 8.1，结果装出的包含 readonly 属性，运行时报 ParseError。
-
docker build卡在composer install步骤，常因网络波动或认证失败 - 容器启动后
require(): failed to open stream，多半是 autoload 没生成或路径错位 - 挂载宿主机
vendor/作 volume，opcache 会拒绝加载（版本不匹配）且 UID/GID 冲突导致写入失败
多阶段构建中 composer install 的正确位置和参数
关键不是“怎么装”，而是“在哪装、装完怎么交出去”。第一阶段必须独立、干净、可缓存。
- 用专用 builder 镜像：
FROM php:8.3-cli AS builder（比composer:2更可控，能统一扩展） - 顺序必须是：
COPY composer.json composer.lock ./→RUN composer install --no-dev --optimize-autoloader --classmap-authoritative --no-progress --no-interaction - 私有包认证用
--secret id=composer_auth,src=$HOME/.composer/auth.json，别硬编码 token - 别
COPY . .到 builder 阶段，除非真要跑post-install-cmd脚本
移交 vendor 到运行镜像时的权限和路径陷阱
移交不是简单 COPY --from=builder 就完事。权限、用户、路径三者错一个，FPM 就起不来。
- 目标镜像（如
php:8.3-fpm-alpine）需提前建非 root 用户：RUN adduser -D -u 1001 -s /bin/sh app -
COPY --from=builder --chown=app:app /app/vendor ./vendor—— 必须带--chown，否则vendor/属主仍是root -
WORKDIR和vendor/必须在同一挂载点下，否则 PSR-4 自动加载找不到类（比如WORKDIR /var/www/html，就别把vendor放到/app/vendor） - 若用
docker-compose.yml挂载源码卷，明确排除vendor/和composer.lock，防止覆盖容器内已安装的依赖
config.platform.php 锁定 PHP 版本这个动作容易被跳过
即使 builder 镜像用了 PHP 8.3，如果 composer.json 里没设 "config": {"platform": {"php": "8.3.12"}}，Composer 仍可能根据当前环境推测能力，装入仅兼容 8.4 的包——比如某高版本 symfony/console 已弃用 8.3 不支持的语法，运行时报错却查不到源头。
- 验证是否生效：
RUN composer show --platform必须输出你锁定的 PHP 版本 - CI 构建失败时，先检查
composer --version是否可执行，再确认php -v和config.platform.php是否一致 -
composer install报Could not open input file: composer.phar，90% 是没把composer放进$PATH，用官方命令安装：curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
真正难的不是写对一行 COPY，而是让 builder 阶段的 PHP 版本、扩展、config.platform.php 和最终运行镜像的环境严丝合缝——差一个小版本，就可能卡在 autoload 加载那一毫秒。
