Laravel Sail – 乌鸦嘴文档中心

介绍

Laravel Sail (opens in a new tab) 是一个轻量级的命令行界面，用于与 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 (opens in a new tab)）上均受支持。

安装与设置

所有新的 Laravel 应用程序都会自动安装 Laravel Sail，因此您可以立即开始使用它。要了解如何创建新的 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

[!WARNING]
如果您使用的是 Docker Desktop for Linux，您应该通过执行以下命令使用 default Docker 上下文：docker context use default。

添加其他服务

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

php artisan sail:add

使用 Devcontainers

如果您想在 Devcontainer (opens in a new tab) 中进行开发，您可以向 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

然而，您可能希望配置一个 Shell 别名，以便更轻松地执行 Sail 的命令，而不是反复输入 vendor/bin/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 浏览器中通过以下网址访问项目：http://localhost。 (opens in a new tab)

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

sail stop

执行命令

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

在阅读 Laravel 文档时，您经常会看到对 Composer、Artisan 和 Node / NPM 命令的引用，但没有提到 Sail。 这些示例假定这些工具已安装在您的本地计算机上。如果您在本地 Laravel 开发环境中使用 Sail，则应使用 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 安装：

sail composer require laravel/sanctum

为现有应用安装 Composer 依赖

如果您正在与团队开发一个应用程序，您可能不是最初创建 Laravel 应用程序的人。因此，在您将应用程序的仓库克隆到本地计算机后，包括 Sail 在内的应用程序的 Composer 依赖都不会被安装。

您可以通过导航到应用程序的目录并执行以下命令来安装应用程序的依赖。此命令使用一个包含 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 卷 (opens in a new tab)，以便即使在停止和重新启动容器时，数据库中存储的数据也能被持久保存。

此外，MySQL 容器第一次启动时，它将为您创建两个数据库。第一个数据库使用您的 DB_DATABASE 环境变量的值命名，用于您的本地开发。第二个是一个专用的测试数据库，名为 testing，将确保您的测试不会干扰您的开发数据。

一旦您启动了容器，您可以通过在应用程序的 .env 文件中将 DB_HOST 环境变量设置为 mysql，来连接到应用程序内的 MySQL 实例。

要从本地机器连接到您的应用程序的 MySQL 数据库，您可以使用图形化的数据库管理应用程序，如 TablePlus (opens in a new tab)。默认情况下，MySQL 数据库可在 localhost 端口 3306 访问，访问凭据与您的 DB_USERNAME 和 DB_PASSWORD 环境变量的值相对应。或者，您可以以 root 用户连接，该用户也使用您的 DB_PASSWORD 环境变量的值作为密码。

Redis

您的应用程序的 docker-compose.yml 文件还包含一个 Redis (opens in a new tab) 容器的条目。这个容器使用 Docker 卷 (opens in a new tab)，以便即使在停止和重新启动容器时，Redis 数据中存储的数据也能被持久保存。一旦您启动了容器，您可以通过在应用程序的 .env 文件中将 REDIS_HOST 环境变量设置为 redis，来连接到应用程序内的 Redis 实例。

要从本地机器连接到您的应用程序的 Redis 数据库，您可以使用图形化的数据库管理应用程序，如 TablePlus (opens in a new tab)。默认情况下，Redis 数据库可在 localhost 端口 6379 访问。

Meilisearch

如果您在安装 Sail 时选择安装 Meilisearch (opens in a new tab) 服务，您的应用程序的 docker-compose.yml 文件将包含这个与 Laravel Scout 集成的强大搜索引擎的条目。一旦您启动了容器，您可以通过在应用程序的 .env 文件中将 MEILISEARCH_HOST 环境变量设置为 http://meilisearch:7700，来连接到应用程序内的 Meilisearch 实例。

从您的本地机器，您可以通过在您的网络浏览器中导航到 http://localhost:7700 来访问 Meilisearch 的基于网络的管理面板。

Typesense

如果您在安装 Sail 时选择安装 Typesense (opens in a new tab) 服务，您的应用程序的 docker-compose.yml 文件将包含这个快速、开源的搜索引擎的条目，它与 Laravel Scout 原生集成。一旦您启动了容器，您可以通过设置以下环境变量来连接到应用程序内的 Typesense 实例：

TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz

从您的本地机器，您可以通过 http://localhost:8108 访问 Typesense 的 API。

文件存储

如果您计划在应用程序的生产环境中运行时使用 Amazon S3 来存储文件，您可能希望在安装 Sail 时安装 MinIO (opens in a new tab) 服务。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=http://localhost:9000/local

您可以通过 MinIO 控制台创建桶，该控制台可在 http://localhost:8900 访问。MinIO 控制台的默认用户名是 sail，默认密码是 password。

[!WARNING]
在使用 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 (opens in a new tab) 的服务条目。Mailpit 会在本地开发期间拦截您的应用程序发送的电子邮件，并提供一个方便的 Web 界面，以便您可以在浏览器中预览您的电子邮件消息。当使用 Sail 时，Mailpit 的默认主机是 mailpit，可通过端口 1025 访问：

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

当 Sail 运行时，您可以在以下地址访问 Mailpit Web 界面：http://localhost:8025 (opens in a new tab)

容器 CLI

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

sail shell
 
sail root-shell

要启动一个新的 Laravel Tinker (opens in a new tab) 会话，您可以执行 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，您可以使用该 URL 访问您的应用程序：

sail share

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

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

如果您想为您的共享站点选择子域名，您可以在执行 share 命令时提供 subdomain 选项：

sail share --subdomain=my-sail-site

[!NOTE]
share 命令由 Expose (opens in a new tab) 提供支持，这是 BeyondCode (opens in a new tab) 提供的一个开源隧道服务。

使用 Xdebug 进行调试

Laravel Sail 的 Docker 配置包括对 Xdebug (opens in a new tab) 的支持，这是一个流行且强大的 PHP 调试器。为了启用 Xdebug，您需要在应用程序的 .env 文件中添加一些变量来配置 Xdebug (opens in a new tab)。要启用 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 使用

当运行 Artisan 命令时，可以使用 sail debug 命令来启动一个调试会话：

# 运行一个不带 Xdebug 的 Artisan 命令...
sail artisan migrate
 
# 运行一个带 Xdebug 的 Artisan 命令...
sail debug migrate

Xdebug 浏览器使用

要在通过 Web 浏览器与应用程序交互时调试您的应用程序，请按照 Xdebug 提供的说明 (opens in a new tab) 从 Web 浏览器启动 Xdebug 会话。

如果您使用的是 PhpStorm，请查看 JetBrains 关于零配置调试 (opens in a new tab) 的文档。

[!WARNING]
Laravel Sail 依赖 artisan serve 来服务您的应用程序。从 Laravel 版本 8.53.0 开始，artisan serve 命令仅接受 XDEBUG_CONFIG 和 XDEBUG_MODE 变量。较旧版本的 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

Laravel Reverb Laravel Sanctum