必须通过sail composer update在容器内执行，而非宿主机直接运行；否则因PHP环境、扩展、配置不匹配导致失败，常见错误包括命令未找到、解析错误或扩展缺失。
在 Laravel Sail 容器里运行 composer update
直接在宿主机上敲 composer update 会失败——它找不到容器内的 PHP 环境、扩展或配置。必须通过 sail composer update 触发容器内执行。
常见错误现象：
-
Command 'composer' not found：本地没装 Composer，或装了但没加到 PATH -
PHP Parse error或ext-mbstring missing：宿主机 PHP 版本/扩展不匹配，而容器内才是真实运行环境
实操要点：
- 确保容器已启动：
sail up -d或sail up（前台运行） - 命令必须在项目根目录（含
docker-compose.yml和composer.json的目录）下执行 - 如需更新开发依赖，加
--with-all-dependencies或显式用--dev，例如：sail composer update --dev - 若卡住或报错后 vendor 权限异常，先
sail composer clear-cache，再sail composer install替代 update（更稳定）
用 docker-compose run 手动进容器执行
适用于非 Sail 项目、自定义 Docker Compose 配置，或需要临时调试的场景。此时不能依赖 sail 命令封装。
关键点：
- 确认服务名：查看
docker-compose.yml中 PHP 容器的服务名（常为app、php或web） - 指定用户：避免权限问题，加
-u $(id -u):$(id -g)让容器内进程以当前用户 UID/GID 运行 - 挂载当前目录：用
-v "$(pwd):/app"确保容器能读写本地composer.json和vendor/
典型命令：
docker-compose run --rm -u $(id -u):$(id -g) -v "$(pwd):/app" -w /app app composer update
注意：app 是服务名，需按实际替换；--rm 防止残留退出容器。
composer update 在容器中失败的三个高频原因
不是 Composer 本身出错，而是容器环境与宿主机协作时的隐性断层。
常见表现与应对：
-
file_put_contents(.../installed.json): Permission denied：容器内用户（如www-data）和宿主机用户 UID 不一致，导致挂载卷写入失败 → 在Dockerfile中加USER root+chown -R $UID:$GID /app/vendor，或改用docker-compose run -u指定 UID -
Could not fetch https://repo.packagist.org：容器无外网访问，或 DNS 解析失败 → 检查docker-compose.yml是否配置了network_mode: "host"或自定义 DNS（如114.114.114.114） - 更新中途挂起、CPU 占满、无输出：宿主机文件监听器（如 PhpStorm、VS Code 的文件索引）锁住了
vendor/中的文件 → 临时关闭 IDE 的文件自动同步，或加--no-scripts跳过 post-update-cmd
CI/CD 流水线里怎么安全跑 composer update
生产构建阶段严禁直接 update，但 CI 中有时需生成新 composer.lock。重点是隔离、可重现、不污染缓存。
推荐做法：
- 始终使用多阶段构建：第一阶段用
composer/composer:2-bin镜像执行composer update --no-interaction --no-progress，第二阶段 COPYvendor/到精简运行镜像 - CI 脚本开头加
rm -rf vendor/ && rm composer.lock，避免继承上一次构建的权限或旧 lock 文件 - 若需保留 lock 文件一致性，改用
composer install --no-dev+composer outdated检查，而非盲目 update - 镜像源必须显式配置：在 CI 步骤中加
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，防止因 Packagist 临时不可用导致失败
真正容易被忽略的是：容器内执行 composer update 时，composer.json 的 config.platform 设置是否与容器 PHP 版本对齐——比如设了 "php": "8.1"，但容器实际是 8.2，可能导致某些包拒绝安装，且错误提示极不直观。
