必须使用 sail composer 而非本地 Composer，因其在 laravel.test 容器内执行，确保 PHP 版本、扩展、权限及 autoload 映射与运行环境完全一致，避免 Class not found 等错误。
直接用 sail composer，别碰本地 Composer
在 Laravel Sail 环境里，composer 不是你电脑上装的那个——它只存在于 laravel.test 容器里。你本地装不装、装哪个版本，完全无关；强行用宿主机的 composer install，大概率会生成错乱的 vendor/autoload.php 或权限错误的文件，导致 sail artisan 报 Class not found。
-
sail composer install：首次克隆项目后必须运行，所有依赖都在容器内解包、写权限、生成自动加载映射 -
sail composer require laravel/sanctum：加新包时唯一安全方式，避免本地 PHP 版本与容器不一致引发的依赖解析失败 -
sail composer dump-autoload -o：修改了composer.json但没增删包？用这个刷新 autoload，比install更轻量 - 别用
sudo composer或手动chown -R $USER:www-data vendor/——容器里用户是sail，宿主机改权限只会让下次sail up启动失败
sail composer 命令背后到底发生了什么
你敲下 sail composer update，Sail 并不是“转发命令”那么简单。它会：
- 检查
laravel.test容器是否在运行；若未启动，先docker start它（不拉起整个 stack） - 以
sail用户身份进入容器，工作目录自动设为项目根路径（即/var/www/html） - 读取容器内的 PHP 和 Composer 配置（比如
memory_limit=-1、opcache.enable=0），和你本地环境彻底隔离 - 生成的
vendor/文件归属是sail:sail，且所有 .so 扩展都匹配容器架构（M1 Mac 上用本地 Composer 装的 x86_64 扩展，在 arm64 容器里根本加载不了）
常见报错和对应解法
这些错误几乎全因绕过 sail composer 引起：
-
PHP Fatal error: Uncaught Error: Class 'Illuminate\Foundation\Application' not found→ 删掉宿主机的vendor/和composer.lock，再跑sail composer install -
Could not open input file: artisan（执行sail composer ...时）→ 检查当前目录是不是项目根目录（docker-compose.yml和sail脚本所在处） -
Permission denied @ dir_s_mkdir→ 不是磁盘满，是宿主机上vendor/被其他用户（比如 root）写过，sail down && rm -rf vendor/ composer.lock && sail composer install -
Package operations: 0 installs, 0 updates, 0 removals却提示更新失败 →composer.json里有语法错误，用sail composer validate先验一下
什么时候真得用镜像直跑 Composer？
极少数场景下，sail composer 启不来（比如容器卡死、laravel.test 构建失败），你可以临时用官方 Sail Composer 镜像绕过：
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
docker run --rm -v $(pwd):/opt -w /opt -u "$(id -u):$(id -g)" laravelsail/php82-composer:latest composer install
注意三点：-u 参数确保生成的 vendor/ 权限匹配宿主机用户；laravelsail/php82-composer:latest 必须和 docker-compose.yml 中 laravel.test 的 PHP 版本一致；这仅用于救急，不能替代日常的 sail composer 流程。
最常被忽略的一点：哪怕你只是改了一行 composer.json 的注释，也得重新 sail composer install ——因为 autoload 映射和依赖锁文件是强绑定的，容器不会“猜”你改没改。
