在 Laravel Sail 环境中必须使用 sail composer 命令（如 sail composer install）在 PHP 容器内执行 Composer 操作，以确保 PHP 版本、扩展和依赖环境一致，避免宿主机直接运行导致的兼容性问题。
在 Laravel Sail 环境中运行 Composer 命令，不能直接在宿主机上执行 composer install，因为依赖需要安装在容器内（尤其是 PHP 和扩展环境一致），否则可能引发版本或扩展不匹配问题。正确做法是通过 Sail 代理命令到 PHP 容器中执行。
使用 sail composer 执行常见操作
Sail 提供了内置的 sail composer 命令，它会自动进入运行中的 laravel.test（PHP）容器，并在其中执行 Composer。这是最推荐、最安全的方式：
-
sail composer install—— 安装依赖（读取composer.lock） -
sail composer update—— 更新依赖并生成新composer.lock -
sail composer require foo/bar—— 添加新包（自动写入composer.json并安装） -
sail composer dump-autoload—— 重新生成自动加载映射（适合修改了类命名空间后）
确保容器已启动且 PHP 容器就绪
运行前请确认 Sail 容器已启动：
- 执行
sail up -d启动后台服务（包括laravel.test容器） - 用
sail ps查看容器状态，确保laravel.test显示为Up - 若提示 “No such service: laravel.test”，检查项目根目录是否有
docker-compose.yml且未被重命名或修改服务名
需要自定义 Composer 配置？临时挂载或进容器调试
极少数情况需指定 Composer 配置（如私有仓库 auth）或调试安装过程：
- 临时挂载本地
auth.json：sail run --rm -v $(pwd)/auth.json:/root/.composer/auth.json composer config --global --auth github-oauth.github.com abc123 - 交互式进入容器排查：
sail shell→ 进入后手动运行composer diagnose或查看日志 - 注意：容器内 Composer 版本由 Sail 镜像决定（通常与 Laravel 推荐版本一致），不建议在容器内升级 Composer 自身，除非明确需要
避免在宿主机直接运行 composer（除非明确知道后果）
虽然宿主机装了 Composer 可能“也能跑”，但存在明显风险：
- PHP 版本/扩展差异导致
composer install结果与容器不一致（例如本地有 gd，容器没开，但依赖却装上了） - Windows/macOS 主机路径权限或符号链接问题，使
vendor在容器内不可用或行为异常 -
composer.lock中记录的平台配置（platform）可能与容器实际环境冲突
基本上就这些。坚持用 sail composer，既省心又保环境一致，开发时少踩一半坑。
