根本原因是MySQL容器未被拉起或未正确链接；php artisan sail:install必须执行并勾选MySQL，否则docker-compose.yml中无services.mysql块，DB_HOST=mysql因服务不存在而Connection refused。
直接用 laravelsail/php80-composer 镜像启动的容器，不是“开箱即用”的万能环境——它只提供基础 PHP + Composer 运行时，MySQL、Redis 等服务必须靠 docker-compose.yml 显式声明并启动，否则 DB_HOST=mysql 会直接报错 Connection refused。
为什么 sail up 启动后 Laravel 连不上 MySQL
根本原因不是配置写错了，而是 MySQL 容器压根没被拉起或没被正确链接。
-
php artisan sail:install必须执行，且在交互中勾选 MySQL（默认不选）；跳过这步，docker-compose.yml里就没有services.mysql块 -
DB_HOST只能填mysql（Docker 内部服务名），填127.0.0.1或localhost会连宿主机，不是容器内网 - 改完
.env后必须重启容器：sail down && sail up -d，PHP 容器不会热重载环境变量 - MySQL 容器启动慢于 PHP 容器，首次访问白屏常见；可等 10 秒再刷新，或加
healthcheck（别删）
sail mysql 能进但 TablePlus 连不上
这是宿主机和容器网络映射没对齐的典型表现。
- 查实际端口映射：
docker port mysql 3306，输出类似0.0.0.0:3307，就用3307连 TablePlus -
FORWARD_DB_PORT=3307设在.env里才生效；设了但没sail down && sail up，端口不会变 - Windows 用户若用 WSL2，确保 Docker Desktop 设置为 “Use the WSL 2 based engine”
修改 PHP 文件后 500 错误，清 opcache 不起作用
因为 Sail 的 PHP 容器默认启用了 opcache，且缓存路径不在宿主机可见范围，opcache_reset() 在本地调用无效。
立即学习“PHP免费学习笔记（深入）”；
- 进容器执行清理：
sail php -r 'opcache_reset();' - 或者更彻底：重启 PHP 容器：
sail restart php（前提是docker-compose.yml中定义了phpservice） - 开发阶段可临时禁用：在
docker-compose.yml的phpservice 下加环境变量OPCACHE_ENABLE=0
最易被忽略的是：Sail 不是黑盒，它的所有行为都由 docker-compose.yml 驱动。任何“失效”，第一反应不该是重装，而是 cat docker-compose.yml 看对应 service 是否存在、端口是否暴露、depends_on 是否写错——镜像只是载体，编排才是关键。
