Laravel怎么安装Sail环境_Laravel如何使用Docker开发【入门】

新项目直接用 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，不然修改根本不生效。