新项目直接用 Sail 是因为其预置了与 Laravel 版本强对齐的 PHP、MySQL、Redis 等开发环境，避免手动配置镜像差异、挂载遗漏等问题；Sail 本质是轻量级 shell 封装，调用本地 docker-compose，无需全局 PHP/Composer。
为什么新项目直接用 sail 而不是自己写 docker-compose.yml
因为 Laravel 官方维护的 sail 不只是个脚本，它把 PHP 版本、MySQL 配置、Redis、MailHog、Node.js 环境这些开发刚需都预设好了，且和当前 Laravel 版本强对齐。你自己手写容易漏掉 php:8.2-cli 和 php:8.2-apache 的镜像差异，或者忘记挂载 .env 到容器内导致配置不生效。
-
sail是一个轻量级 shell 封装，本质就是调用本地docker-compose，不依赖全局 PHP 或 Composer - 执行
./vendor/bin/sail up时，它自动读取docker-compose.yml（由sail install生成），无需手动docker-compose build - 常见错误：
Command "sail" is not defined—— 这是因为还没运行php artisan sail:install，该命令会生成docker-compose.yml并在./vendor/bin/下放好可执行脚本
sail up 启动后访问不了 http://localhost 怎么办
默认情况下 sail up 启动的是 Apache + PHP-FPM 组合，但入口服务名是 laravel.test，不是 localhost。Docker 内部网络不直通 host 的 localhost，必须靠 Hosts 文件或浏览器直连端口。
- 检查
docker-compose.yml中services.apache.ports是否为- '80:80'；如果不是，比如写了- '8080:80'，就得访问http://localhost:8080 - Mac / Windows 用户如果用 Docker Desktop，默认支持
http://laravel.test，但需先加 hosts：运行sudo sh -c "echo '127.0.0.1 laravel.test' >> /etc/hosts" - Linux 用户没有内置 DNS 解析，建议直接用
http://localhost或改用127.0.0.1:80，别依赖域名 - 启动后执行
./vendor/bin/sail ps确认apache容器状态是Up，不是Restarting—— 后者通常因.env里DB_HOST=mysqld写错（正确应为mysql，对应服务名）
数据库连不上：SQLSTATE[HY000] [2002] Connection refused
这个错误几乎全是容器间网络没打通，不是密码错了，也不是端口没开。Laravel 应用跑在 apache 容器里，它要连的是同 docker-compose 网络下的 mysql 容器，而不是宿主机的 3306。
-
.env中必须写DB_HOST=mysql（不是127.0.0.1，也不是localhost），因为mysql是docker-compose.yml里定义的服务名 -
DB_PORT保持默认3306即可，不要改成宿主机映射的端口（如33060），容器内通信走内部端口 - 首次运行迁移前，先等 MySQL 容器就绪：执行
./vendor/bin/sail mysql -u root -psecret -e "SHOW DATABASES;"，能返回结果再跑./vendor/bin/sail artisan migrate - 如果用了
mysql:8.0镜像，注意 Laravel 9+ 默认兼容，但 Laravel 8 需在config/database.php的mysql配置里加'options' => [\PDO::ATTR_EMULATE_PREPARES => true]，否则报Authentication plugin 'caching_sha2_password' cannot be loaded
想换 PHP 版本或加扩展，改哪儿
不能改 Dockerfile（sail 默认不用自定义构建），而是通过 docker-compose.yml 中的 image 字段切换官方镜像，并用 build.args 控制扩展。Laravel Sail 的镜像命名规则很明确：laravelsail/phpXX-composer。
- PHP 8.2 + 常用扩展：把
image: laravelsail/php81-composer改成image: laravelsail/php82-composer - 加
gd扩展：在对应服务（如apache）下加build:块，用args: { EXT_GD: 'true' }，然后运行sail build --no-cache - 别碰
php.ini宿主机挂载 ——sail的镜像是编译时写死配置的，运行时挂载会覆盖整个/etc/php，导致 FPM 无法启动 - 性能影响：启用
xdebug会让请求慢 3–5 倍，开发调试时用./vendor/bin/sail up --build启动带 xdebug 的镜像，日常开发建议关掉（删掉EXT_XDEBUG: 'true'并重建）
最常被忽略的是：每次改完 docker-compose.yml 或 .env，都要重新运行 ./vendor/bin/sail build（如果有 build:）和 ./vendor/bin/sail up -d，不然修改根本不生效。
