根本原因是PHP官方镜像不含Composer，需手动安装；网络、缓存、权限、路径任一环节异常均会导致失败，必须严格配置镜像源、正确挂载缓存与vendor、统一PHP版本及平台约束。
Composer 在 Docker 容器里跑不起来，不是项目写得有问题，而是环境没对齐——官方 PHP 镜像默认不带 composer 命令，网络、缓存、权限、路径任何一个环节断了，composer install 就会卡住或失败。
为什么 docker run php:8.2-cli composer --version 报 command not found
根本原因：PHP 官方镜像（如 php:8.2-cli）只含 PHP 解释器，不含 composer 可执行文件。它不是“没装好”，是压根没放进去。
- 别用
apt install composer（Debian/Ubuntu 镜像）——源里版本老旧，常和composer.json中的php平台约束冲突 - 推荐安装方式：
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer - Alpine 镜像必须先装
curl和openssl：apk add --no-cache curl openssl - 验证是否生效：
docker run --rm php:8.2-cli sh -c 'which composer && composer --version'，这步通不过，后续全白搭
docker build 时 composer install 卡在 “Resolving dependencies”
本质是网络 + 缓存失效问题。Docker 构建过程无法复用宿主机的 ~/.composer/cache，又默认直连境外 packagist.org，国内环境下极易超时。
- 构建前加环境变量强制切镜像源：
RUN COMPOSER_REPO_PACKAGIST=https://mirrors.aliyun.com/composer/ composer install - 或者在
Dockerfile中全局配置：RUN composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/ - COPY 顺序必须严格：
COPY composer.json composer.lock ./→RUN composer install→COPY . .；否则只要改一行代码，整个依赖层就失效重装 - 加
--no-interaction --no-progress --optimize-autoloader --no-dev，避免交互卡住、减少输出干扰、提升 autoload 性能
vendor 目录挂载进容器后 Class not found 或 Permission denied
这是 macOS/Windows 与 Linux 容器 UID/GID 不一致导致的典型权限错乱。宿主机上生成的 vendor 文件属主是 UID 1000，而 PHP-FPM 容器内默认以 UID 82 或 1001 运行，读不了。
- 开发阶段：**不要挂载整个
vendor目录**；只挂载源码（如./src:/app/src），然后在容器内跑composer install - CI 或必须挂载场景：提前在宿主机运行
chown -R 1001:1001 vendor（假设容器用户 UID=1001），或在Dockerfile里统一建用户：useradd -u 1001 -m app - 挂载
~/.composer/cache到容器内可复用缓存：volumes: - ~/.composer/cache:/root/.composer/cache（注意路径对应容器内用户家目录） - 执行一次
composer dump-autoload -o，避免因文件系统缓存未刷新导致类加载路径错误
怎么让 composer install 真正只在构建时跑一次，而不是每次启动都重来
把 composer install 放进 docker-compose.yml 的 command 或 entrypoint 是危险操作——它会让每次 docker-compose up 都重新解析依赖，既慢又不可控，还可能因网络波动失败导致容器起不来。
- 正确做法：用多阶段构建，在构建镜像第一阶段完成
vendor安装，第二阶段只复制/app/vendor和应用代码 - 示例第一阶段：
FROM composer/composer:2-bin as builder→COPY composer.* ./→RUN composer install --no-dev - 第二阶段：
FROM php:8.2-fpm-alpine→COPY --from=builder /app/vendor /app/vendor - 生产镜像中彻底移除
composer二进制，减小攻击面和体积；开发镜像可保留，但仅用于docker-compose run --rm php composer ...
最易被忽略的一点：你本地 composer.json 里写的 "config": {"platform": {"php": "8.1"}}，和容器里实际运行的 PHP 版本不一致时，composer install 会静默降级依赖，甚至装错扩展——务必确认三者对齐：composer 版本、容器内 php -v、config.platform.php。
