Laravel Sail 是 Laravel 官方基于 Docker 的轻量级本地开发环境工具，封装了 sail 命令与预配置 docker-compose.yml，开箱即用，解决版本统一、权限同步、命令转发等痛点；适用于单项目快速启动，不适用于多项目共享服务、深度定制或生产部署。

Laravel Sail 是 Laravel 官方提供的、基于 Docker 的轻量级本地开发环境封装工具，它不是独立的 Docker 编排系统，而是 sail 命令行脚本 + 预配置的

为什么不用直接写 docker-compose.yml？

直接写 docker-compose.yml 当然可以，但 Laravel Sail 解决了几个高频痛点：

• 统一管理 PHP 版本、MySQL/PostgreSQL/Redis 等服务版本与默认配置（比如 MySQL 默认启用 utf8mb4_0900_as_cs 排序规则）
• 自动挂载当前项目目录到容器内 /var/www/html，且保持用户 UID/GID 一致，避免文件权限混乱（www-data 写不了 storage/）
• sail artisan、sail npm run dev 等命令自动转发到对应容器，无需手动 docker exec -it
• 一键启停：sail up -d / sail down，比记一堆 docker-compose 参数更直观

如何初始化并启动 Sail？

前提是已安装 Docker Desktop（或 Linux 上的 Docker Engine + docker-compose v2.2+），且项目根目录下已有 composer.json（Laravel 9+ 新项目默认带 Sail）。

若项目未初始化 Sail：

php artisan sail:install

该命令会：

• 生成 docker-compose.yml（含 laravel.test、mysql、redis 等服务）
• 创建 ./vendor/bin/sail 可执行脚本（Linux/macOS）或 sail.bat（Windows）
• 提示你选择数据库类型和是否启用 Selenium、Meilisearch 等可选服务

然后运行：

./vendor/bin/sail up -d

首次启动会拉取镜像（如 laravelsail/php82-composer），耗时较长；后续启动很快。

常见问题：访问不了 http://localhost 或 artisan 命令报错

典型现象包括：

• 浏览器打开 http://localhost 显示 “This site can’t be reached”
• sail artisan migrate 报错 SQLSTATE[HY000] [2002] Connection refused
• sail npm run dev 启动后热更新不生效，或 WebSocket 连接失败

原因和对策：

• docker-compose.yml 中 laravel.test 的 ports 没暴露 80/443：确认有 - '80:80' 或 - '127.0.0.1:80:80'，不要写成 - '8080:80' 却还用 localhost 访问
• MySQL 容器没就绪就执行迁移：加 --wait 或等 sail ps 显示所有状态为 Up 再操作；也可在 .env 中设 DB_HOST=mysql（非 127.0.0.1）
• NPM 开发服务器监听 localhost 而非 0.0.0.0：修改 package.json 中 "dev": "vite --host" 或 "dev": "mix --host 0.0.0.0"
• Windows 上 WSL2 与 Docker Desktop 网络隔离：关闭 WSL2 后重开终端，或改用 sail shell 进入容器内部调试

什么时候不该用 Sail？

Sail 是为“单项目快速启动”设计的，不适合以下场景：

• 需要多项目共用一套 MySQL/Redis（Sail 每个项目都起独立容器，端口易冲突）
• 要深度定制 PHP 扩展（如 grpc、sqlsrv），Sail 提供的镜像不含这些，需自己构建基础镜像
• 生产环境部署参考——Sail 的镜像是开发向的（含 Xdebug、Composer、Node.js），体积大、不安全，不能直接用于线上
• CI/CD 流水线中复用——Sail 脚本依赖宿主机的 docker 和 docker-compose，CI 环境通常用更精简的纯 docker-compose 或 GitHub Actions 自定义 runner

真正麻烦的从来不是启动容器，而是搞清哪个服务该连哪个 host、哪个端口、谁先启动谁后启动、文件权限怎么同步——Sail 把这些默认值固化下来，省掉前 30 分钟踩坑时间。但一旦需求超出它的预设边界，就得切回原生 Docker 工作流。