Laravel Sail
简介
Laravel Sail 是一个轻量级的命令行界面,用于与 Laravel 的默认 Docker 开发环境进行交互。 Sail 为使用 PHP、MySQL 和 Redis 构建 Laravel 应用程序提供了一个很好的起点,而无需事先具备 Docker 经验。
Sail 的核心是 docker-compose.yml
文件和存储在项目根目录的 sail
脚本。 sail
脚本提供了一个 CLI,其中包含与 docker-compose.yml
文件定义的 Docker 容器进行交互的便捷方法。
macOS、Linux 和 Windows(通过 WSL2)均支持 Laravel Sail。
安装和设置
Laravel Sail 会自动安装在所有新的 Laravel 应用程序中,因此您可以立即开始使用它。 要了解如何创建新的 Laravel 应用程序,请查阅 Laravel 的 安装文档,了解您的操作系统。 在安装过程中,系统会要求您选择您的应用程序将与之交互的 Sail 支持的服务。
将 Sail 安装到现有应用中
如果您有兴趣将 Sail 与现有的 Laravel 应用程序一起使用,您可以简单地使用 Composer 包管理器安装 Sail。 当然,这些步骤假定您现有的本地开发环境允许您安装 Composer 依赖项
1composer require laravel/sail --dev
安装 Sail 后,您可以运行 sail:install
Artisan 命令。 此命令会将 Sail 的 docker-compose.yml
文件发布到应用程序的根目录,并修改您的 .env
文件,其中包含连接到 Docker 服务所需的 环境变量
1php artisan sail:install
最后,您可以启动 Sail。 要继续学习如何使用 Sail,请继续阅读本文档的其余部分
1./vendor/bin/sail up
如果您使用的是 Linux 版 Docker Desktop,则应使用 default
Docker 上下文,方法是执行以下命令:docker context use default
。
添加其他服务
如果您想向现有的 Sail 安装中添加其他服务,可以运行 sail:add
Artisan 命令
1php artisan sail:add
使用 Devcontainers
如果您想在 Devcontainer 中进行开发,您可以向 sail:install
命令提供 --devcontainer
选项。 --devcontainer
选项将指示 sail:install
命令将默认的 .devcontainer/devcontainer.json
文件发布到应用程序的根目录
1php artisan sail:install --devcontainer
重新构建 Sail 镜像
有时您可能想要完全重新构建 Sail 镜像,以确保所有镜像的包和软件都是最新的。 您可以使用 build
命令完成此操作
1docker compose down -v2 3sail build --no-cache4 5sail up
配置 Shell 别名
默认情况下,Sail 命令是使用所有新的 Laravel 应用程序都包含的 vendor/bin/sail
脚本调用的
1./vendor/bin/sail up
但是,您可能希望配置一个 shell 别名,以便更轻松地执行 Sail 的命令,而不是重复键入 vendor/bin/sail
来执行 Sail 命令
1alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'
为确保始终可用,您可以将其添加到主目录中的 shell 配置文件中,例如 ~/.zshrc
或 ~/.bashrc
,然后重新启动 shell。
配置 shell 别名后,您只需键入 sail
即可执行 Sail 命令。 本文档其余部分的示例将假定您已配置此别名
1sail up
启动和停止 Sail
Laravel Sail 的 docker-compose.yml
文件定义了各种 Docker 容器,这些容器协同工作以帮助您构建 Laravel 应用程序。 这些容器中的每一个都是 docker-compose.yml
文件的 services
配置中的一个条目。 laravel.test
容器是主要的应用程序容器,它将为您的应用程序提供服务。
在启动 Sail 之前,您应确保本地计算机上没有其他 Web 服务器或数据库正在运行。 要启动应用程序的 docker-compose.yml
文件中定义的所有 Docker 容器,您应执行 up
命令
1sail up
要在后台启动所有 Docker 容器,您可以以“分离”模式启动 Sail
1sail up -d
应用程序的容器启动后,您可以在 Web 浏览器中通过以下网址访问该项目:https://127.0.0.1。
要停止所有容器,您可以简单地按 Control + C 停止容器的执行。 或者,如果容器在后台运行,您可以使用 stop
命令
1sail stop
执行命令
使用 Laravel Sail 时,您的应用程序在 Docker 容器中执行,并且与本地计算机隔离。 但是,Sail 提供了一种便捷的方式来针对您的应用程序运行各种命令,例如任意 PHP 命令、Artisan 命令、Composer 命令和 Node / NPM 命令。
在阅读 Laravel 文档时,您经常会看到对 Composer、Artisan 和 Node / NPM 命令的引用,这些命令不引用 Sail。 这些示例假定这些工具已安装在您的本地计算机上。 如果您使用 Sail 作为本地 Laravel 开发环境,则应使用 Sail 执行这些命令
1# Running Artisan commands locally...2php artisan queue:work3 4# Running Artisan commands within Laravel Sail...5sail artisan queue:work
执行 PHP 命令
可以使用 php
命令执行 PHP 命令。 当然,这些命令将使用为您的应用程序配置的 PHP 版本执行。 要了解有关 Laravel Sail 可用的 PHP 版本的更多信息,请查阅 PHP 版本文档
1sail php --version2 3sail php script.php
执行 Composer 命令
可以使用 composer
命令执行 Composer 命令。 Laravel Sail 的应用程序容器包含 Composer 安装
1sail composer require laravel/sanctum
为现有应用程序安装 Composer 依赖项
如果您正在与团队一起开发应用程序,您可能不是最初创建 Laravel 应用程序的人。 因此,在您将应用程序的存储库克隆到本地计算机后,将不会安装任何应用程序的 Composer 依赖项(包括 Sail)。
您可以通过导航到应用程序的目录并执行以下命令来安装应用程序的依赖项。 此命令使用一个包含 PHP 和 Composer 的小型 Docker 容器来安装应用程序的依赖项
1docker run --rm \2 -u "$(id -u):$(id -g)" \3 -v "$(pwd):/var/www/html" \4 -w /var/www/html \5 laravelsail/php84-composer:latest \6 composer install --ignore-platform-reqs
使用 laravelsail/phpXX-composer
镜像时,您应使用与您计划用于应用程序的 PHP 版本相同的版本(80
、81
、82
、83
或 84
)。
执行 Artisan 命令
可以使用 artisan
命令执行 Laravel Artisan 命令
1sail artisan queue:work
执行 Node / NPM 命令
可以使用 node
命令执行 Node 命令,而可以使用 npm
命令执行 NPM 命令
1sail node --version2 3sail npm run dev
如果您愿意,可以使用 Yarn 而不是 NPM
1sail yarn
与数据库交互
MySQL
您可能已经注意到,您的应用程序的 docker-compose.yml
文件包含 MySQL 容器的条目。 此容器使用 Docker 卷,以便即使在停止和重新启动容器时,数据库中存储的数据也会持久保存。
此外,MySQL 容器首次启动时,它将为您创建两个数据库。 第一个数据库使用您的 DB_DATABASE
环境变量的值命名,用于您的本地开发。 第二个是名为 testing
的专用测试数据库,它将确保您的测试不会干扰您的开发数据。
启动容器后,您可以通过在应用程序的 .env
文件中将 DB_HOST
环境变量设置为 mysql
来连接到应用程序中的 MySQL 实例。
要从本地计算机连接到应用程序的 MySQL 数据库,您可以使用图形数据库管理应用程序,例如 TablePlus。 默认情况下,MySQL 数据库可通过 localhost
端口 3306 访问,访问凭据与您的 DB_USERNAME
和 DB_PASSWORD
环境变量的值相对应。 或者,您可以作为 root
用户连接,这也使用您的 DB_PASSWORD
环境变量的值作为其密码。
MongoDB
如果您在安装 Sail 时选择安装 MongoDB 服务,则应用程序的 docker-compose.yml
文件包含 MongoDB Atlas Local 容器的条目,该容器提供具有 Atlas 功能(如 搜索索引)的 MongoDB 文档数据库。 此容器使用 Docker 卷,以便即使在停止和重新启动容器时,数据库中存储的数据也会持久保存。
启动容器后,您可以通过在应用程序的 .env
文件中将 MONGODB_URI
环境变量设置为 mongodb://mongodb:27017
来连接到应用程序中的 MongoDB 实例。 默认情况下禁用身份验证,但您可以设置 MONGODB_USERNAME
和 MONGODB_PASSWORD
环境变量以在启动 mongodb
容器之前启用身份验证。 然后,将凭据添加到连接字符串
1MONGODB_USERNAME=user2MONGODB_PASSWORD=laravel3MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017
为了将 MongoDB 与您的应用程序无缝集成,您可以安装 MongoDB 维护的官方软件包。
要从本地计算机连接到应用程序的 MongoDB 数据库,您可以使用图形界面,例如 Compass。 默认情况下,MongoDB 数据库可通过 localhost
端口 27017
访问。
Redis
您的应用程序的 docker-compose.yml
文件还包含 Redis 容器的条目。 此容器使用 Docker 卷,以便即使在停止和重新启动容器时,Redis 实例中存储的数据也会持久保存。 启动容器后,您可以通过在应用程序的 .env
文件中将 REDIS_HOST
环境变量设置为 redis
来连接到应用程序中的 Redis 实例。
要从本地计算机连接到应用程序的 Redis 数据库,您可以使用图形数据库管理应用程序,例如 TablePlus。 默认情况下,Redis 数据库可通过 localhost
端口 6379 访问。
Valkey
如果您在安装 Sail 时选择安装 Valkey 服务,则应用程序的 docker-compose.yml
文件将包含 Valkey 的条目。 此容器使用 Docker 卷,以便即使在停止和重新启动容器时,Valkey 实例中存储的数据也会持久保存。 您可以通过在应用程序的 .env
文件中将 REDIS_HOST
环境变量设置为 valkey
来连接到应用程序中的此容器。
要从本地计算机连接到应用程序的 Valkey 数据库,您可以使用图形数据库管理应用程序,例如 TablePlus。 默认情况下,Valkey 数据库可通过 localhost
端口 6379 访问。
Meilisearch
如果您在安装 Sail 时选择安装 Meilisearch 服务,则应用程序的 docker-compose.yml
文件将包含此强大搜索引擎的条目,该搜索引擎与 Laravel Scout 集成。 启动容器后,您可以通过将 MEILISEARCH_HOST
环境变量设置为 http://meilisearch:7700
来连接到应用程序中的 Meilisearch 实例。
从本地计算机,您可以通过在 Web 浏览器中导航到 https://127.0.0.1:7700
来访问 Meilisearch 的基于 Web 的管理面板。
Typesense
如果您在安装 Sail 时选择安装 Typesense 服务,则应用程序的 docker-compose.yml
文件将包含此闪电般快速的开源搜索引擎的条目,该搜索引擎与 Laravel Scout 原生集成。 启动容器后,您可以通过设置以下环境变量来连接到应用程序中的 Typesense 实例
1TYPESENSE_HOST=typesense2TYPESENSE_PORT=81083TYPESENSE_PROTOCOL=http4TYPESENSE_API_KEY=xyz
从本地计算机,您可以通过 https://127.0.0.1:8108
访问 Typesense 的 API。
文件存储
如果您计划在生产环境中运行应用程序时使用 Amazon S3 存储文件,您可能希望在安装 Sail 时安装 MinIO 服务。 MinIO 提供了一个 S3 兼容的 API,您可以使用它在本地使用 Laravel 的 s3
文件存储驱动程序进行开发,而无需在生产 S3 环境中创建“测试”存储桶。 如果您选择在安装 Sail 时安装 MinIO,则 MinIO 配置部分将添加到应用程序的 docker-compose.yml
文件中。
默认情况下,您的应用程序的 filesystems
配置文件已包含 s3
磁盘的磁盘配置。 除了使用此磁盘与 Amazon S3 交互外,您还可以通过简单地修改控制其配置的相关环境变量来使用它与任何 S3 兼容的文件存储服务(例如 MinIO)进行交互。 例如,使用 MinIO 时,您的文件系统环境变量配置应定义如下
1FILESYSTEM_DISK=s32AWS_ACCESS_KEY_ID=sail3AWS_SECRET_ACCESS_KEY=password4AWS_DEFAULT_REGION=us-east-15AWS_BUCKET=local6AWS_ENDPOINT=http://minio:90007AWS_USE_PATH_STYLE_ENDPOINT=true
为了使 Laravel 的 Flysystem 集成在使用 MinIO 时生成正确的 URL,您应定义 AWS_URL
环境变量,使其与应用程序的本地 URL 匹配,并在 URL 路径中包含存储桶名称
1AWS_URL=https://127.0.0.1:9000/local
您可以通过 MinIO 控制台创建存储桶,该控制台可通过 https://127.0.0.1:8900
访问。 MinIO 控制台的默认用户名是 sail
,默认密码是 password
。
使用 MinIO 时,不支持通过 temporaryUrl
方法生成临时存储 URL。
运行测试
Laravel 提供了出色的开箱即用测试支持,您可以使用 Sail 的 test
命令来运行应用程序的 功能和单元测试。 Pest / PHPUnit 接受的任何 CLI 选项也可以传递给 test
命令
1sail test2 3sail test --group orders
Sail test
命令等效于运行 test
Artisan 命令
1sail artisan test
默认情况下,Sail 将创建一个专用的 testing
数据库,以便您的测试不会干扰数据库的当前状态。 在默认的 Laravel 安装中,Sail 还会配置您的 phpunit.xml
文件,以便在执行测试时使用此数据库
1<env name="DB_DATABASE" value="testing"/>
Laravel Dusk
Laravel Dusk 提供了一个富有表现力、易于使用的浏览器自动化和测试 API。 借助 Sail,您可以运行这些测试,而无需在本地计算机上安装 Selenium 或其他工具。 要开始使用,请取消注释应用程序的 docker-compose.yml
文件中的 Selenium 服务
1selenium:2 image: 'selenium/standalone-chrome'3 extra_hosts:4 - 'host.docker.internal:host-gateway'5 volumes:6 - '/dev/shm:/dev/shm'7 networks:8 - sail
接下来,确保应用程序的 docker-compose.yml
文件中的 laravel.test
服务具有 selenium
的 depends_on
条目
1depends_on:2 - mysql3 - redis4 - selenium
最后,您可以通过启动 Sail 并运行 dusk
命令来运行 Dusk 测试套件
1sail dusk
Apple Silicon 上的 Selenium
如果您的本地计算机包含 Apple Silicon 芯片,则您的 selenium
服务必须使用 selenium/standalone-chromium
镜像
1selenium:2 image: 'selenium/standalone-chromium'3 extra_hosts:4 - 'host.docker.internal:host-gateway'5 volumes:6 - '/dev/shm:/dev/shm'7 networks:8 - sail
预览邮件
Laravel Sail 的默认 docker-compose.yml
文件包含 Mailpit 的服务条目。 Mailpit 会拦截您的应用程序在本地开发期间发送的电子邮件,并提供一个方便的 Web 界面,以便您可以在浏览器中预览您的电子邮件消息。 使用 Sail 时,Mailpit 的默认主机是 mailpit
,可通过端口 1025 访问
1MAIL_HOST=mailpit2MAIL_PORT=10253MAIL_ENCRYPTION=null
当 Sail 运行时,您可以通过以下网址访问 Mailpit Web 界面:https://127.0.0.1:8025
容器 CLI
有时您可能希望在应用程序的容器中启动 Bash 会话。 您可以使用 shell
命令连接到应用程序的容器,从而允许您检查其文件和已安装的服务,以及在容器中执行任意 shell 命令
1sail shell2 3sail root-shell
要启动新的 Laravel Tinker 会话,您可以执行 tinker
命令
1sail tinker
PHP 版本
Sail 当前支持通过 PHP 8.4、8.3、8.2、8.1 或 PHP 8.0 为您的应用程序提供服务。 Sail 使用的默认 PHP 版本当前为 PHP 8.4。 要更改用于为应用程序提供服务的 PHP 版本,您应更新应用程序的 docker-compose.yml
文件中 laravel.test
容器的 build
定义
1# PHP 8.4 2context: ./vendor/laravel/sail/runtimes/8.4 3 4# PHP 8.3 5context: ./vendor/laravel/sail/runtimes/8.3 6 7# PHP 8.2 8context: ./vendor/laravel/sail/runtimes/8.2 9 10# PHP 8.111context: ./vendor/laravel/sail/runtimes/8.112 13# PHP 8.014context: ./vendor/laravel/sail/runtimes/8.0
此外,您可能希望更新您的 image
名称以反映您的应用程序正在使用的 PHP 版本。 此选项也在您的应用程序的 docker-compose.yml
文件中定义
1image: sail-8.2/app
更新应用程序的 docker-compose.yml
文件后,您应重新构建容器镜像
1sail build --no-cache2 3sail up
Node 版本
Sail 默认安装 Node 20。 要更改构建镜像时安装的 Node 版本,您可以更新应用程序的 docker-compose.yml
文件中 laravel.test
服务的 build.args
定义
1build:2 args:3 WWWGROUP: '${WWWGROUP}'4 NODE_VERSION: '18'
更新应用程序的 docker-compose.yml
文件后,您应重新构建容器镜像
1sail build --no-cache2 3sail up
共享您的站点
有时您可能需要公开共享您的站点,以便为同事预览您的站点或测试与您的应用程序的 Webhook 集成。 要共享您的站点,您可以使用 share
命令。 执行此命令后,您将获得一个随机的 laravel-sail.site
URL,您可以使用该 URL 访问您的应用程序
1sail share
通过 share
命令共享您的站点时,您应使用应用程序的 bootstrap/app.php
文件中的 trustProxies
中间件方法配置应用程序的受信任代理。 否则,URL 生成辅助函数(例如 url
和 route
)将无法确定 URL 生成期间应使用的正确 HTTP 主机
1->withMiddleware(function (Middleware $middleware) {2 $middleware->trustProxies(at: '*');3})
如果您想为共享站点选择子域名,您可以在执行 share
命令时提供 subdomain
选项
1sail share --subdomain=my-sail-site
share
命令由 Expose 提供支持,Expose 是 BeyondCode 提供的开源隧道服务。
使用 Xdebug 调试
Laravel Sail 的 Docker 配置包括对 Xdebug 的支持,Xdebug 是 PHP 的流行且功能强大的调试器。 要启用 Xdebug,请确保您已发布 Sail 配置。 然后,将以下变量添加到应用程序的 .env
文件中以配置 Xdebug
1SAIL_XDEBUG_MODE=develop,debug,coverage
接下来,确保您发布的 php.ini
文件包含以下配置,以便 Xdebug 在指定的模式下激活
1[xdebug]2xdebug.mode=${XDEBUG_MODE}
修改 php.ini
文件后,请记住重新构建 Docker 镜像,以便您对 php.ini
文件的更改生效
1sail build --no-cache
Linux 主机 IP 配置
在内部,XDEBUG_CONFIG
环境变量定义为 client_host=host.docker.internal
,以便为 Mac 和 Windows (WSL2) 正确配置 Xdebug。 如果您的本地计算机运行的是 Linux 并且您使用的是 Docker 20.10+,则 host.docker.internal
可用,并且无需手动配置。
对于低于 20.10 的 Docker 版本,Linux 上不支持 host.docker.internal
,您需要手动定义主机 IP。 为此,通过在 docker-compose.yml
文件中定义自定义网络,为您的容器配置静态 IP
1networks: 2 custom_network: 3 ipam: 4 config: 5 - subnet: 172.20.0.0/16 6 7services: 8 laravel.test: 9 networks:10 custom_network:11 ipv4_address: 172.20.0.2
设置静态 IP 后,在应用程序的 .env 文件中定义 SAIL_XDEBUG_CONFIG 变量
1SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"
Xdebug CLI 用法
sail debug
命令可用于在运行 Artisan 命令时启动调试会话
1# Run an Artisan command without Xdebug...2sail artisan migrate3 4# Run an Artisan command with Xdebug...5sail debug migrate
Xdebug 浏览器用法
要在通过 Web 浏览器与应用程序交互时调试应用程序,请按照 Xdebug 提供的说明从 Web 浏览器启动 Xdebug 会话。
如果您使用的是 PhpStorm,请查看 JetBrains 关于零配置调试的文档。
Laravel Sail 依赖于 artisan serve
来为您的应用程序提供服务。 artisan serve
命令仅接受 Laravel 8.53.0 版本及更高版本中的 XDEBUG_CONFIG
和 XDEBUG_MODE
变量。 较低版本的 Laravel(8.52.0 及更低版本)不支持这些变量,并且不会接受调试连接。
自定义
由于 Sail 只是 Docker,您可以自由自定义几乎所有关于它的内容。 要发布 Sail 自己的 Dockerfile,您可以执行 sail:publish
命令
1sail artisan sail:publish
运行此命令后,Laravel Sail 使用的 Dockerfile 和其他配置文件将放置在应用程序根目录中的 docker
目录中。 自定义 Sail 安装后,您可能希望更改应用程序的 docker-compose.yml
文件中应用程序容器的镜像名称。 执行此操作后,使用 build
命令重新构建应用程序的容器。 如果您使用 Sail 在单台计算机上开发多个 Laravel 应用程序,则为应用程序镜像分配唯一名称尤为重要
1sail build --no-cache