Laravel Sail

简介
安装和设置
启动和停止 Sail
执行命令
与数据库交互
- MySQL
- Redis
- Meilisearch
- Typesense
文件存储
运行测试
- Laravel Dusk
预览电子邮件
容器 CLI
PHP 版本
Node 版本
共享你的网站
使用 Xdebug 调试
- Xdebug CLI 使用
- Xdebug 浏览器使用
定制

简介

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 文件发布到应用程序的根目录，并修改你的 .env 文件，以包含连接到 Docker 服务所需的環境變數。

php artisan sail:install

最后，你可以启动 Sail。要继续学习如何使用 Sail，请继续阅读本文档的其余部分。

./vendor/bin/sail up

如果你使用 Docker Desktop for Linux，则应该使用 default Docker 上下文，方法是执行以下命令：docker context use default。

添加其他服务

如果你想在现有的 Sail 安装中添加其他服务，可以运行 sail:add Artisan 命令。

php artisan sail:add

使用 Devcontainers

如果你想在 Devcontainer 中进行开发，则可以在 sail:install 命令中提供 --devcontainer 选项。--devcontainer 选项将指示 sail:install 命令将默认的 .devcontainer/devcontainer.json 文件发布到应用程序的根目录。

php artisan sail:install --devcontainer

重建 Sail 镜像

有时你可能想完全重建 Sail 镜像，以确保镜像的所有软件包和软件都是最新的。可以使用 build 命令来完成此操作。

docker compose down -v
 
sail build --no-cache
 
sail up

配置 Shell 别名

默认情况下，Sail 命令使用包含在所有新的 Laravel 应用程序中的 vendor/bin/sail 脚本调用。

./vendor/bin/sail up

但是，你可能不想为了执行 Sail 命令而重复输入 vendor/bin/sail，因此你可能希望配置一个 Shell 别名，让你可以更轻松地执行 Sail 命令。

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

为了确保始终可以使用它，可以将其添加到你的主目录中的 Shell 配置文件（例如 ~/.zshrc 或 ~/.bashrc）中，然后重新启动 Shell。

配置 Shell 别名后，可以通过简单地输入 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 浏览器中访问该项目，地址为：https://127.0.0.1.

要停止所有容器，可以简单地按下 Control + C 来停止容器的执行。或者，如果容器在后台运行，可以使用 stop 命令。

sail stop

执行命令

使用 Laravel Sail 时，你的应用程序将在 Docker 容器中执行，并与你的本地计算机隔离。但是，Sail 提供了一种便捷的方式来对你的应用程序运行各种命令，例如任意 PHP 命令、Artisan 命令、Composer 命令和 Node / NPM 命令。

在阅读 Laravel 文档时，你经常会看到关于 Composer、Artisan 和 Node / NPM 命令的引用，这些引用没有提及 Sail。 这些示例假设这些工具安装在你的本地计算机上。如果你在本地 Laravel 开发环境中使用 Sail，则应使用 Sail 来执行这些命令。

# Running Artisan commands locally...
php artisan queue:work
 
# Running Artisan commands within Laravel Sail...
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 安装。

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/php83-composer:latest \
    composer install --ignore-platform-reqs

使用 laravelsail/phpXX-composer 镜像时，应使用与你计划用于应用程序的相同 PHP 版本（80、81、82 或 83）。

执行 Artisan 命令

可以使用 artisan 命令执行 Laravel Artisan 命令。

sail artisan queue:work

执行 Node / NPM 命令

可以使用 node 命令执行 Node 命令，可以使用 npm 命令执行 NPM 命令。

sail node --version
 
sail npm run dev

如果你愿意，可以使用 Yarn 代替 NPM。

sail 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环境变量的值作为其密码。

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浏览器中导航到https://127.0.0.1:7700来访问Meilisearch的基于Web的管理面板。

Typesense

如果您在安装Sail时选择了安装Typesense服务，您的应用程序的docker-compose.yml文件将包含此闪电般快速、开源的搜索引擎的条目，该引擎与Laravel Scout原生集成。启动容器后，您可以通过设置以下环境变量来连接到应用程序内的Typesense实例。

TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_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时，您的文件系统环境变量配置应定义如下。

FILESYSTEM_DISK=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的Flysystem集成在使用MinIO时生成正确的URL，您应该定义AWS_URL环境变量，使其与应用程序的本地URL匹配，并在URL路径中包含存储桶名称。

AWS_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命令。

sail test
 
sail test --group orders

Sail的test命令等同于运行test Artisan命令。

sail artisan test

默认情况下，Sail将创建一个专用的testing数据库，以使您的测试不会干扰数据库的当前状态。在默认的Laravel安装中，Sail还将配置您的phpunit.xml文件，以便在执行测试时使用此数据库。

<env name="DB_DATABASE" value="testing"/>

Laravel Dusk

Laravel Dusk提供了一个表达性、易于使用的浏览器自动化和测试API。得益于Sail，您可以在不安装Selenium或其他工具的情况下在本地计算机上运行这些测试。要开始，请取消应用程序的docker-compose.yml文件中的Selenium服务的注释。

selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

接下来，确保应用程序的docker-compose.yml文件中的laravel.test服务对selenium有一个depends_on条目。

depends_on:
    - mysql
    - redis
    - selenium

最后，您可以通过启动Sail并运行dusk命令来运行Dusk测试套件。

sail dusk

Apple Silicon上的Selenium

如果您的本地机器包含Apple Silicon芯片，您的selenium服务必须使用selenium/standalone-chromium镜像。

selenium:
    image: 'selenium/standalone-chromium'
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

预览电子邮件

Laravel Sail的默认docker-compose.yml文件包含一个用于Mailpit的服务条目。Mailpit会拦截应用程序在本地开发期间发送的电子邮件，并提供一个方便的Web界面，以便您可以在浏览器中预览电子邮件。使用Sail时，Mailpit的默认主机是mailpit，可以通过端口1025访问。

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

当Sail运行时，您可以在以下地址访问Mailpit Web界面：https://127.0.0.1:8025

容器 CLI

有时您可能希望在应用程序的容器内启动一个Bash会话。您可以使用shell命令连接到您的应用程序的容器，这将允许您检查其文件和已安装的服务，以及在容器内执行任意shell命令。

sail shell
 
sail root-shell

要启动一个新的Laravel Tinker会话，您可以执行tinker命令。

sail tinker

PHP 版本

Sail目前支持通过PHP 8.3、8.2、8.1或PHP 8.0提供您的应用程序。Sail使用的默认PHP版本目前是PHP 8.3。要更改用于提供应用程序的PHP版本，您应该更新应用程序的docker-compose.yml文件中的laravel.test容器的build定义。

# PHP 8.3
context: ./vendor/laravel/sail/runtimes/8.3
 
# PHP 8.2
context: ./vendor/laravel/sail/runtimes/8.2
 
# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1
 
# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0

此外，您可能希望更新您的image名称以反映应用程序使用的PHP版本。此选项也在应用程序的docker-compose.yml文件中定义。

image: sail-8.2/app

更新应用程序的docker-compose.yml文件后，您应该重建您的容器镜像。

sail build --no-cache
 
sail up

Node 版本

Sail默认安装Node 20。要更改在构建镜像时安装的Node版本，您可以在应用程序的docker-compose.yml文件中的laravel.test服务的build.args定义中进行更新。

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '18'

更新应用程序的docker-compose.yml文件后，您应该重建您的容器镜像。

sail build --no-cache
 
sail up

有时您可能需要公开共享您的网站，以便为同事预览您的网站，或者测试与应用程序的Webhook集成。要共享您的网站，您可以使用share命令。执行此命令后，您将获得一个随机的laravel-sail.site URL，您可以使用它来访问您的应用程序。

sail share

通过share命令共享您的网站时，您应该使用应用程序的bootstrap/app.php文件中的trustProxies中间件方法配置应用程序的受信任代理。否则，URL生成助手（例如url和route）将无法确定在URL生成期间应使用的正确HTTP主机。

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(at: '*');
})

如果您希望为共享的网站选择子域名，您可以在执行share命令时提供subdomain选项。

sail share --subdomain=my-sail-site

share命令由Expose提供支持，Expose是BeyondCode提供的一种开源隧道服务。

使用 Xdebug 调试

Laravel Sail的Docker配置包括对Xdebug的支持，Xdebug是一个流行且功能强大的PHP调试器。为了启用Xdebug，您需要在应用程序的.env文件中添加一些变量来配置Xdebug。要启用Xdebug，您必须在启动Sail之前设置适当的模式。

SAIL_XDEBUG_MODE=develop,debug,coverage

Linux主机IP配置

在内部，XDEBUG_CONFIG环境变量被定义为client_host=host.docker.internal，以便Xdebug能够为Mac和Windows（WSL2）正确配置。如果您的本地机器运行的是Linux，并且您使用的是Docker 20.10+，host.docker.internal是可用的，无需手动配置。

对于早于20.10的Docker版本，host.docker.internal在Linux上不受支持，您需要手动定义主机IP。为此，请通过在您的docker-compose.yml文件中定义一个自定义网络，为您的容器配置一个静态IP。

networks:
  custom_network:
    ipam:
      config:
        - subnet: 172.20.0.0/16
 
services:
  laravel.test:
    networks:
      custom_network:
        ipv4_address: 172.20.0.2

设置静态IP后，请在应用程序的.env文件中定义SAIL_XDEBUG_CONFIG变量。

SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Xdebug CLI 使用

sail debug命令可用于在运行Artisan命令时启动调试会话。

# Run an Artisan command without Xdebug...
sail artisan migrate
 
# Run an Artisan command with Xdebug...
sail debug migrate

Xdebug 浏览器使用

要通过Web浏览器与应用程序交互时调试应用程序，请按照Xdebug提供的说明从Web浏览器启动Xdebug会话。

如果您使用的是PhpStorm，请查看JetBrains关于零配置调试的文档。

Laravel Sail依赖于artisan serve来提供您的应用程序。artisan serve命令仅接受XDEBUG_CONFIG和XDEBUG_MODE变量，从Laravel版本8.53.0开始。较旧的Laravel版本（8.52.0及以下）不支持这些变量，并且不会接受调试连接。

定制

由于Sail只是Docker，因此您可以自由地自定义几乎所有关于它的内容。要发布Sail自己的Dockerfile，您可以执行sail:publish命令。

sail artisan sail:publish

运行此命令后，Laravel Sail使用的Dockerfile和其他配置文件将被放置在应用程序根目录中的docker目录中。自定义Sail安装后，您可能希望更改应用程序的docker-compose.yml文件中应用程序容器的镜像名称。完成此操作后，使用build命令重建应用程序的容器。如果您使用Sail在一台机器上开发多个Laravel应用程序，则为应用程序镜像分配一个唯一的名称尤为重要。

sail build --no-cache