根本原因是官方PHP镜像默认不带Composer，需在Dockerfile中用curl安装；挂载vendor权限错乱源于宿主机与容器UID/GID不一致；务必校验composer、PHP及config.platform.php三者版本耦合。
Composer 容器内执行失败：找不到 composer 命令
根本原因不是 Docker 镜像没装 Composer，而是多数官方 PHP 镜像（比如 php:8.2-cli）默认不带 composer 可执行文件。它只是个 PHP 脚本，得自己装。
实操建议：
- 在
Dockerfile里用curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer安装，别用apt install composer—— Ubuntu 源里的版本太老，常和项目composer.json的 PHP 版本约束冲突 - 如果用多阶段构建，把
composer install放到构建阶段，而不是运行时；否则每次启动容器都重装依赖，慢且不可控 - 确认镜像里
PATH包含/usr/local/bin，否则即使装了也提示command not found
vendor 目录挂载进容器后权限错乱、autoload 失效
本地 macOS/Windows 和 Linux 容器的 UID/GID 不一致，导致挂载进来的 vendor 文件属主变成 root 或其他用户，PHP 进程读不了，Class not found 错误就来了。
实操建议：
- 开发时别挂载整个
vendor目录进容器；改用只挂载源码（./src:/app/src），在容器内跑composer install生成vendor - 若必须挂载（如 CI 场景），提前在宿主机用
chown -R 1001:1001 vendor（假设容器里 PHP 用户 UID=1001），或在Dockerfile里用useradd -u 1001 app统一身份 -
composer dump-autoload -o在容器内执行一次，避免因文件系统缓存导致类加载路径没刷新
使用 composer install --no-dev 但容器启动仍报缺少 dev 依赖
常见于 Laravel、Symfony 项目：某些“开发时才需要”的包（比如 phpunit/phpunit）被写进了 require 而非 require-dev，或者用了 config.platform 强制降级 PHP 版本，结果 --no-dev 没起作用。
实操建议：
- 检查
composer.json，确认所有测试/调试类库都在require-dev下；用composer show --dev快速验证 - 构建镜像时加
--no-interaction --optimize-autoloader --no-progress，减少干扰项；别省掉--no-interaction，否则遇到交互式提示会卡住 - CI 构建前先跑
composer validate，它能发现platform配置与当前环境冲突等隐藏问题
Docker Compose 启动时自动执行 composer install 的安全边界
直接在 command 或 entrypoint 里写 composer install && php-fpm 看似方便，但一旦 composer.json 改了、或网络临时故障，容器就反复重启失败，根本起不来。
实操建议：
- 把
composer install放进Dockerfile的RUN指令，确保镜像是确定性的；运行时只负责启动服务 - 如果真要动态安装（比如共享开发镜像），用包装脚本判断
vendor/autoload.php是否存在，不存在再执行composer install，并设超时和重试次数（timeout 300 composer install || exit 1） - 永远别在生产镜像里保留
composer二进制 —— 它不是运行时依赖，反而增加攻击面和镜像体积
事情说清了就结束。最常被忽略的是：容器里 composer 的版本、PHP 版本、以及 composer.json 里 config.platform.php 三者之间的隐式耦合——差一个点，install 就可能静默降级依赖，线上出问题都查不到源头。
