sail 是 laravel 官方封装的最小可行开发环境，无需手动配置 docker、php 或 nginx；访问需用 http://laravel.test（需 hosts 绑定），mysql 连接依赖服务名与密码一致，opcache 需禁用，新增服务后须 sail build --no-cache 再启动。
直接用 sail 就能跑起来，不用写 docker-compose.yml、不配 PHP 扩展、不调 Nginx 转发规则——这是 Laravel 官方封装好的最小可行路径。其他方案（比如自己写 compose 文件或用 Laradock）适合需要深度定制的场景，但对 90% 的新项目和协作开发来说，sail 是更稳、更快、更少出错的选择。
为什么 sail 启动后访问 404 或白屏
不是代码没挂载，而是 Nginx 配置没生效或路由未匹配：
-
sail默认使用内置的laravel.test域名，浏览器必须访问http://laravel.test（不是localhost或127.0.0.1）；Windows/macOS 需提前在/etc/hosts加一行：127.0.0.1 laravel.test - 首次启动后，
public/index.php必须存在且可读；如果用create-project生成，确认没漏掉--prefer-dist参数导致 vendor 未解压 - 检查
APP_URL是否设为http://laravel.test，否则 Laravel 的 URL 生成器会拼错路径 - 别手动改
nginx.conf——sail自带的配置已适配 Laravel 10+ 的目录结构，改了反而破坏重写规则
sail up -d 后 MySQL 连不上：常见三类错误
报错 SQLSTATE[HY000] [2054]、Connection refused 或 Access denied，本质都是网络或认证层没对齐：
-
DB_HOST=mysql是固定写死的——容器内靠服务名通信，不能写localhost或127.0.0.1 -
DB_PASSWORD=secret必须和docker-compose.yml里mysql服务的MARIA_DB_ROOT_PASSWORD（或MYSQL_ROOT_PASSWORD）一致；Laravel 默认用 root 连，不是 app 用户 - MySQL 8.4+ 默认用
caching_sha2_password插件，PHP 8.2+ 的pdo_mysql支持，但老镜像可能不兼容；加一行MYSQL_DEFAULT_AUTHENTICATION_PLUGIN=mysql_native_password到 .env 更保险
改完 PHP 代码刷新还是旧页面？别只清浏览器缓存
根本原因通常是 OPcache 没关或没重载，不是前端问题：
-
sail的 PHP 容器默认开启 OPcache，开发时必须关掉：在.env加PHP_OPCACHE_ENABLE=0，然后sail down && sail up -d - 改了
config/下的文件（比如app.php），必须执行sail artisan config:clear，否则配置仍走缓存 - 改了 Blade 模板却没更新，检查
storage/framework/views/是否被权限锁住（尤其 WSL2 下），运行sail shell后手动rm -rf storage/framework/views/*
想加 Redis 或 Meilisearch？别硬改 compose 文件
sail 提供了官方集成路径，绕过手动编辑能避免 yaml 语法错误和版本错配：
- 运行
php artisan sail:install，勾选需要的服务（Redis / Meilisearch / Selenium），它会自动重写docker-compose.yml并注入对应环境变量 - 启用 Redis 后，
REDIS_HOST=redis就生效，不用改任何 Laravel 配置；但记得在config/database.php里确认redis的host键值是env('REDIS_HOST', 'redis') - Meilisearch 启动后监听
http://meilisearch:7700，Laravel Scout 默认用这个地址，无需改MEILISEARCH_HOST
真正容易被忽略的点是：每次新增服务后，sail 不会自动重建所有容器，必须显式执行 sail build --no-cache 再 sail up -d，否则新加的镜像层不会加载。这不是 bug，是 Docker 构建缓存机制的正常表现。
