Laravel Sail
介绍
Laravel Sail 是一个轻量级的命令行界面,用于与 Laravel 的默认 Docker 开发环境交互。Sail 提供了一个很好的起点,可以使用 PHP、MySQL 和 Redis 构建 Laravel 应用,而无需事先了解 Docker。
Sail 的核心是存储在项目根目录的 docker-compose.yml
文件和 sail
脚本。sail
脚本提供了一个 CLI,具有方便的方法来与 docker-compose.yml
文件定义的 Docker 容器交互。
Laravel Sail 支持在 macOS、Linux 和 Windows(通过 WSL2)上运行。
安装与设置
Laravel Sail 会自动安装在所有新的 Laravel 应用中,因此您可以立即开始使用它。要了解如何创建新的 Laravel 应用,请查阅 Laravel 的安装文档以获取适用于您的操作系统的说明。在安装过程中,您将被要求选择应用将与哪些 Sail 支持的服务进行交互。
在现有应用中安装 Sail
如果您希望在现有的 Laravel 应用中使用 Sail,可以简单地使用 Composer 包管理器安装 Sail。当然,这些步骤假设您的现有本地开发环境允许您安装 Composer 依赖:
composer require laravel/sail --dev
安装 Sail 后,您可以运行 sail:install
Artisan 命令。此命令会将 Sail 的 docker-compose.yml
文件发布到应用的根目录:
php artisan sail:install
最后,您可以启动 Sail。要继续学习如何使用 Sail,请继续阅读本文档的其余部分:
./vendor/bin/sail up
使用 Devcontainers
如果您希望在 Devcontainer 中进行开发,可以在 sail:install
命令中提供 --devcontainer
选项。--devcontainer
选项将指示 sail:install
命令在应用的根目录发布一个默认的 .devcontainer/devcontainer.json
文件:
php artisan sail:install --devcontainer
配置 Bash 别名
默认情况下,Sail 命令是通过包含在所有新 Laravel 应用中的 vendor/bin/sail
脚本调用的:
./vendor/bin/sail up
然而,您可能希望配置一个 Bash 别名,以便更轻松地执行 Sail 的命令,而不是反复输入 vendor/bin/sail
:
alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'
配置 Bash 别名后,您可以通过简单地输入 sail
来执行 Sail 命令。本文档的其余示例将假设您已配置此别名:
sail up
启动与停止 Sail
Laravel Sail 的 docker-compose.yml
文件定义了多种 Docker 容器,这些容器协同工作以帮助您构建 Laravel 应用。每个容器都是 docker-compose.yml
文件中 services
配置中的一个条目。laravel.test
容器是主要的应用容器,将为您的应用提供服务。
在启动 Sail 之前,您应确保本地计算机上没有其他 Web 服务器或数据库正在运行。要启动应用的 docker-compose.yml
文件中定义的所有 Docker 容器,您应执行 up
命令:
sail up
要在后台启动所有 Docker 容器,可以在“分离”模式下启动 Sail:
sail up -d
一旦应用的容器启动,您可以在 Web 浏览器中访问项目:http://localhost。
要停止所有容器,您可以简单地按 Control + C 停止容器的执行。或者,如果容器在后台运行,可以使用 stop
命令:
sail stop
执行命令
使用 Laravel Sail 时,您的应用在 Docker 容器中执行,并与本地计算机隔离。然而,Sail 提供了一种方便的方法来对应用执行各种命令,如任意 PHP 命令、Artisan 命令、Composer 命令和 Node / NPM 命令。
在阅读 Laravel 文档时,您经常会看到没有引用 Sail 的 Composer、Artisan 和 Node / NPM 命令。 这些示例假设这些工具已安装在本地计算机上。如果您使用 Sail 作为本地 Laravel 开发环境,应使用 Sail 执行这些命令:
# 在本地运行 Artisan 命令...
php artisan queue:work
# 在 Laravel Sail 中运行 Artisan 命令...
sail artisan queue:work
执行 PHP 命令
可以使用 php
命令执行 PHP 命令。当然,这些命令将使用为应用配置的 PHP 版本执行。要了解 Laravel Sail 可用的 PHP 版本,请查阅 PHP 版本文档:
sail php --version
sail php script.php
执行 Composer 命令
可以使用 composer
命令执行 Composer 命令。Laravel Sail 的应用容器包含 Composer 2.x 安装:
sail composer require laravel/sanctum
为现有应用安装 Composer 依赖
如果您与团队一起开发应用,您可能不是最初创建 Laravel 应用的人。因此,在您将应用的存储库克隆到本地计算机后,应用的 Composer 依赖(包括 Sail)都不会被安装。
您可以通过导航到应用目录并执行以下命令来安装应用的依赖。此命令使用一个包含 PHP 和 Composer 的小型 Docker 容器来安装应用的依赖:
docker run --rm \
-u "$(id -u):$(id -g)" \
-v $(pwd):/var/www/html \
-w /var/www/html \
laravelsail/php81-composer:latest \
composer install --ignore-platform-reqs
使用 laravelsail/phpXX-composer
镜像时,您应使用计划用于应用的 PHP 版本(74
、80
或 81
)。
执行 Artisan 命令
可以使用 artisan
命令执行 Laravel Artisan 命令:
sail artisan queue:work
执行 Node / NPM 命令
可以使用 node
命令执行 Node 命令,而 NPM 命令可以使用 npm
命令执行:
sail node --version
sail npm run prod
如果您愿意,可以使用 Yarn 而不是 NPM:
sail yarn
与数据库交互
MySQL
如您所见,应用的 docker-compose.yml
文件中包含一个 MySQL 容器的条目。此容器使用 Docker 卷,以便即使在停止和重启容器时,数据库中存储的数据也能持久化。此外,当 MySQL 容器启动时,它将确保存在一个与 DB_DATABASE
环境变量值匹配的数据库。
启动容器后,您可以通过将应用的 .env
文件中的 DB_HOST
环境变量设置为 mysql
来连接到应用的 MySQL 实例。
要从本地计算机连接到应用的 MySQL 数据库,可以使用图形数据库管理应用,如 TablePlus。默认情况下,MySQL 数据库可通过 localhost
端口 3306 访问。
Redis
应用的 docker-compose.yml
文件中还包含一个 Redis 容器的条目。此容器使用 Docker 卷,以便即使在停止和重启容器时,Redis 数据中存储的数据也能持久化。启动容器后,您可以通过将应用的 .env
文件中的 REDIS_HOST
环境变量设置为 redis
来连接到应用的 Redis 实例。
要从本地计算机连接到应用的 Redis 数据库,可以使用图形数据库管理应用,如 TablePlus。默认情况下,Redis 数据库可通过 localhost
端口 6379 访问。
MeiliSearch
如果您选择在安装 Sail 时安装 MeiliSearch 服务,应用的 docker-compose.yml
文件将包含此强大搜索引擎的条目,该引擎与 Laravel Scout 兼容。启动容器后,您可以通过将 MEILISEARCH_HOST
环境变量设置为 http://meilisearch:7700
来连接到应用的 MeiliSearch 实例。
从本地计算机,您可以通过在 Web 浏览器中导航到 http://localhost:7700
来访问 MeiliSearch 的基于 Web 的管理面板。
文件存储
如果您计划在生产环境中运行应用时使用 Amazon S3 存储文件,您可能希望在安装 Sail 时安装 MinIO 服务。MinIO 提供了一个 S3 兼容的 API,您可以使用它在本地使用 Laravel 的 s3
文件存储驱动进行开发,而无需在生产 S3 环境中创建“测试”存储桶。如果您选择在安装 Sail 时安装 MinIO,应用的 docker-compose.yml
文件中将添加一个 MinIO 配置部分。
默认情况下,应用的 filesystems
配置文件已经包含 s3
磁盘的磁盘配置。除了使用此磁盘与 Amazon S3 交互外,您还可以通过简单地修改控制其配置的相关环境变量来与任何 S3 兼容的文件存储服务(如 MinIO)交互。例如,使用 MinIO 时,文件系统环境变量配置应定义如下:
FILESYSTEM_DRIVER=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true
运行测试
Laravel 提供了出色的测试支持,您可以使用 Sail 的 test
命令运行应用的功能和单元测试。任何 PHPUnit 接受的 CLI 选项也可以传递给 test
命令:
sail test
sail test --group orders
Sail test
命令等同于运行 test
Artisan 命令:
sail artisan test
Laravel Dusk
Laravel Dusk 提供了一个表达性强、易于使用的浏览器自动化和测试 API。感谢 Sail,您可以在本地计算机上无需安装 Selenium 或其他工具即可运行这些测试。要开始,请取消注释应用的 docker-compose.yml
文件中的 Selenium 服务:
selenium:
image: 'selenium/standalone-chrome'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sail
接下来,确保应用的 docker-compose.yml
文件中的 laravel.test
服务有一个 depends_on
条目指向 selenium
:
depends_on:
- mysql
- redis
- selenium
最后,您可以通过启动 Sail 并运行 dusk
命令来运行 Dusk 测试套件:
sail dusk
在 Apple Silicon 上使用 Selenium
如果本地计算机包含 Apple Silicon 芯片,您的 selenium
服务必须使用 seleniarm/standalone-chromium
镜像:
selenium:
image: 'seleniarm/standalone-chromium'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sail
预览邮件
Laravel Sail 的默认 docker-compose.yml
文件包含一个 MailHog 服务条目。MailHog 在本地开发期间拦截应用发送的电子邮件,并提供一个方便的 Web 界面,以便您可以在浏览器中预览电子邮件消息。使用 Sail 时,MailHog 的默认主机是 mailhog
,可通过端口 1025 访问:
MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_ENCRYPTION=null
Sail 运行时,您可以通过访问 http://localhost:8025 来访问 MailHog Web 界面。
容器 CLI
有时您可能希望在应用的容器中启动一个 Bash 会话。您可以使用 shell
命令连接到应用的容器,允许您检查其文件和已安装的服务,并在容器中执行任意 shell 命令:
sail shell
sail root-shell
要启动新的 Laravel Tinker 会话,可以执行 tinker
命令:
sail tinker
PHP 版本
Sail 目前支持通过 PHP 8.1、PHP 8.0 或 PHP 7.4 提供应用服务。Sail 使用的默认 PHP 版本目前是 PHP 8.1。要更改用于提供应用服务的 PHP 版本,您应更新应用的 docker-compose.yml
文件中 laravel.test
容器的 build
定义:
# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1
# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0
# PHP 7.4
context: ./vendor/laravel/sail/runtimes/7.4
此外,您可能希望更新 image
名称以反映应用使用的 PHP 版本。此选项也在应用的 docker-compose.yml
文件中定义:
image: sail-8.1/app
更新应用的 docker-compose.yml
文件后,您应重新构建容器镜像:
sail build --no-cache
sail up
Node 版本
Sail 默认安装 Node 16。要更改构建镜像时安装的 Node 版本,可以更新应用的 docker-compose.yml
文件中 laravel.test
服务的 build.args
定义:
build:
args:
WWWGROUP: '${WWWGROUP}'
NODE_VERSION: '14'
更新应用的 docker-compose.yml
文件后,您应重新构建容器镜像:
sail build --no-cache
sail up
分享您的网站
有时您可能需要公开分享您的网站,以便为同事预览或测试应用的 Webhook 集成。要分享您的网站,可以使用 share
命令。执行此命令后,您将获得一个随机的 laravel-sail.site
URL,您可以使用该 URL 访问应用:
sail share
通过 share
命令分享网站时,您应在 TrustProxies
中间件中配置应用的受信代理。否则,URL 生成助手(如 url
和 route
)将无法确定在 URL 生成期间应使用的正确 HTTP 主机:
/**
* 应用的受信代理。
*
* @var array|string|null
*/
protected $proxies = '*';
如果您希望选择共享网站的子域,可以在执行 share
命令时提供 subdomain
选项:
sail share --subdomain=my-sail-site
share
命令由 Expose 提供支持,这是 BeyondCode 的一个开源隧道服务。
使用 Xdebug 调试
Laravel Sail 的 Docker 配置包括对 Xdebug 的支持,这是一个流行且强大的 PHP 调试器。为了启用 Xdebug,您需要在应用的 .env
文件中添加一些变量以配置 Xdebug。要启用 Xdebug,您必须在启动 Sail 之前设置适当的模式:
SAIL_XDEBUG_MODE=develop,debug
Linux 主机 IP 配置
在内部,XDEBUG_CONFIG
环境变量被定义为 client_host=host.docker.internal
,以便 Xdebug 为 Mac 和 Windows (WSL2) 正确配置。如果本地计算机运行 Linux,您需要手动定义此环境变量。
首先,您应通过运行以下命令确定要添加到环境变量的正确主机 IP 地址。通常,<container-name>
应为提供应用服务的容器名称,通常以 _laravel.test_1
结尾:
docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>
获得正确的主机 IP 地址后,您应在应用的 .env
文件中定义 SAIL_XDEBUG_CONFIG
变量:
SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"
Xdebug CLI 使用
可以使用 sail debug
命令在运行 Artisan 命令时启动调试会话:
# 在没有 Xdebug 的情况下运行 Artisan 命令...
sail artisan migrate
# 在有 Xdebug 的情况下运行 Artisan 命令...
sail debug migrate
Xdebug 浏览器使用
要在通过 Web 浏览器与应用交互时调试应用,请按照 Xdebug 提供的说明 启动 Web 浏览器中的 Xdebug 会话。
如果您使用 PhpStorm,请查看 JetBrain 的关于零配置调试的文档。
Laravel Sail 依赖于 artisan serve
来提供应用服务。artisan serve
命令仅接受 XDEBUG_CONFIG
和 XDEBUG_MODE
变量,从 Laravel 版本 8.53.0 开始。旧版本的 Laravel(8.52.0 及以下)不支持这些变量,并且不接受调试连接。
自定义
由于 Sail 只是 Docker,您可以自由地自定义几乎所有内容。要发布 Sail 自己的 Dockerfiles,您可以执行 sail:publish
命令:
sail artisan sail:publish
运行此命令后,Laravel Sail 使用的 Dockerfiles 和其他配置文件将放置在应用根目录的 docker
目录中。自定义 Sail 安装后,您可能希望更改应用容器在应用的 docker-compose.yml
文件中的镜像名称。完成后,使用 build
命令重新构建应用的容器。为应用镜像分配唯一名称在您在单台计算机上使用 Sail 开发多个 Laravel 应用时尤为重要:
sail build --no-cache