Laravel Sail

介绍
安装和设置
启动和停止 Sail
执行命令
与数据库交互
文件存储
运行测试
- 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 依赖项：

shell

composer require laravel/sail --dev

安装 Sail 后，您可以运行 sail:install Artisan 命令。此命令将 Sail 的 docker-compose.yml 文件发布到您应用程序的根目录，并修改您的 .env 文件，以便连接到 Docker 服务所需的环境变量：

shell

php artisan sail:install

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

shell

./vendor/bin/sail up

如果您在 Linux 上使用 Docker Desktop，您应该通过执行以下命令使用 default Docker 上下文：docker context use default。

添加额外服务

如果您希望向现有的 Sail 安装中添加额外的服务，您可以运行 sail:add Artisan 命令：

shell

php artisan sail:add

使用 Devcontainers

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

shell

php artisan sail:install --devcontainer

重建 Sail 镜像

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

shell

docker compose down -v

sail build --no-cache

sail up

配置 Shell 别名

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

shell

./vendor/bin/sail up

但是，您可能希望配置一个 Shell 别名，以便更轻松地执行 Sail 的命令，而不是重复输入 vendor/bin/sail：

shell

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

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

一旦配置了 Shell 别名，您可以通过简单地输入 sail 来执行 Sail 命令。本文档的其余示例将假设您已配置此别名：

shell

sail up

启动和停止 Sail

Laravel Sail 的 docker-compose.yml 文件定义了多种 Docker 容器，这些容器共同帮助您构建 Laravel 应用程序。每个容器都是您应用程序的 docker-compose.yml 文件中 services 配置的一个条目。laravel.test 容器是将为您提供应用程序的主要应用程序容器。

在启动 Sail 之前，您应该确保本地计算机上没有其他 Web 服务器或数据库正在运行。要启动应用程序的 docker-compose.yml 文件中定义的所有 Docker 容器，您应该执行 up 命令：

shell

sail up

要在后台启动所有 Docker 容器，您可以在“分离”模式下启动 Sail：

shell

sail up -d

一旦应用程序的容器启动，您可以在 Web 浏览器中访问项目：http://localhost。

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

shell

sail stop

执行命令

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

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

shell

# 在本地运行 Artisan 命令...
php artisan queue:work

# 在 Laravel Sail 中运行 Artisan 命令...
sail artisan queue:work

执行 PHP 命令

PHP 命令可以使用 php 命令执行。当然，这些命令将使用为您的应用程序配置的 PHP 版本执行。要了解有关 Laravel Sail 可用的 PHP 版本的更多信息，请查阅 PHP 版本文档：

shell

sail php --version

sail php script.php

执行 Composer 命令

Composer 命令可以使用 composer 命令执行。Laravel Sail 的应用程序容器包含 Composer 安装：

shell

sail composer require laravel/sanctum

为现有应用程序安装 Composer 依赖项

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

您可以通过导航到应用程序的目录并执行以下命令来安装应用程序的依赖项。此命令使用一个包含 PHP 和 Composer 的小型 Docker 容器来安装应用程序的依赖项：

shell

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php84-composer:latest \
    composer install --ignore-platform-reqs

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

执行 Artisan 命令

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

shell

sail artisan queue:work

执行 Node / NPM 命令

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

shell

sail node --version

sail npm run dev

如果您愿意，您可以使用 Yarn 代替 NPM：

shell

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

MongoDB

如果您在安装 Sail 时选择安装 MongoDB 服务，您应用程序的 docker-compose.yml 文件中将包含一个 MongoDB Atlas Local 容器的条目，该容器提供具有 Atlas 功能的 MongoDB 文档数据库，例如搜索索引。此容器使用 Docker 卷以便在停止和重启容器时，存储在数据库中的数据得以持久化。

一旦您启动了容器，您可以通过在应用程序的 .env 文件中将 MONGODB_URI 环境变量设置为 mongodb://mongodb:27017 来连接到应用程序的 MongoDB 实例。默认情况下，身份验证是禁用的，但您可以在启动 mongodb 容器之前设置 MONGODB_USERNAME 和 MONGODB_PASSWORD 环境变量以启用身份验证。然后，将凭据添加到连接字符串中：

ini

MONGODB_USERNAME=user
MONGODB_PASSWORD=laravel
MONGODB_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 浏览器中导航到 http://localhost:7700 来访问 Meilisearch 的基于 Web 的管理面板。

Typesense

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

ini

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

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

文件存储

如果您计划在生产环境中使用 Amazon S3 存储文件，您可能希望在安装 Sail 时安装 MinIO 服务。MinIO 提供与 S3 兼容的 API，您可以使用它在本地开发中使用 Laravel 的 s3 文件存储驱动，而无需在生产 S3 环境中创建“测试”存储桶。如果您选择在安装 Sail 时安装 MinIO，将在您应用程序的 docker-compose.yml 文件中添加 MinIO 配置部分。

默认情况下，您应用程序的 filesystems 配置文件中已经包含了 s3 磁盘的配置。除了使用此磁盘与 Amazon S3 进行交互外，您还可以通过简单地修改控制其配置的相关环境变量来与任何 S3 兼容的文件存储服务（如 MinIO）进行交互。例如，在使用 MinIO 时，您的文件系统环境变量配置应定义如下：

ini

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 路径中包含存储桶名称：

ini

AWS_URL=http://localhost:9000/local

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

在使用 MinIO 时，通过 temporaryUrl 方法生成临时存储 URL 是不支持的。

运行测试

Laravel 提供了出色的测试支持，您可以使用 Sail 的 test 命令运行应用程序的功能和单元测试。任何被 Pest / PHPUnit 接受的 CLI 选项也可以传递给 test 命令：

shell

sail test

sail test --group orders

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

shell

sail artisan test

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

xml

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

Laravel Dusk

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

yaml

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

接下来，确保您应用程序的 docker-compose.yml 文件中的 laravel.test 服务具有 depends_on 条目，指向 selenium：

yaml

depends_on:
    - mysql
    - redis
    - selenium

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

shell

sail dusk

Apple Silicon 上的 Selenium

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

yaml

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 端口访问：

ini

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

当 Sail 正在运行时，您可以在 http://localhost:8025 访问 Mailpit 的 Web 界面。

容器 CLI

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

shell

sail shell

sail root-shell

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

shell

sail 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 定义：

yaml

# PHP 8.4
context: ./vendor/laravel/sail/runtimes/8.4

# 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 文件中定义：

yaml

image: sail-8.2/app

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

shell

sail build --no-cache

sail up

Node 版本

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

yaml

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

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

shell

sail build --no-cache

sail up

共享您的网站

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

shell

sail share

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

php

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

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

shell

sail share --subdomain=my-sail-site

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

使用 Xdebug 调试

Laravel Sail 的 Docker 配置包括对 Xdebug 的支持，这是一个流行且强大的 PHP 调试器。要启用 Xdebug，请确保您已发布 Sail 配置。然后，将以下变量添加到您应用程序的 .env 文件中，以配置 Xdebug：

ini

SAIL_XDEBUG_MODE=develop,debug,coverage

接下来，确保您发布的 php.ini 文件包含以下配置，以便在指定模式下激活 Xdebug：

ini

[xdebug]
xdebug.mode=${XDEBUG_MODE}

修改 php.ini 文件后，请记得重建 Docker 镜像，以便您的更改生效：

shell

sail build --no-cache

Linux 主机 IP 配置

在内部，XDEBUG_CONFIG 环境变量被定义为 client_host=host.docker.internal，以便 Xdebug 在 Mac 和 Windows（WSL2）上正确配置。如果您的本地计算机运行的是 Linux，并且您使用的是 Docker 20.10 及更高版本，则不需要手动配置。

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

yaml

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 变量：

ini

SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Xdebug CLI 使用

可以使用 sail debug 命令在运行 Artisan 命令时启动调试会话：

shell

# 在没有 Xdebug 的情况下运行 Artisan 命令...
sail artisan migrate

# 在 Xdebug 的情况下运行 Artisan 命令...
sail 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 命令：

shell

sail artisan sail:publish

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

shell

sail build --no-cache

Laravel Sail ​

介绍 ​

安装和设置 ​

将 Sail 安装到现有应用程序中 ​

添加额外服务 ​

使用 Devcontainers ​

重建 Sail 镜像 ​

配置 Shell 别名 ​

启动和停止 Sail ​

执行命令 ​

执行 PHP 命令 ​

执行 Composer 命令 ​

为现有应用程序安装 Composer 依赖项 ​

执行 Artisan 命令 ​

执行 Node / NPM 命令 ​

与数据库交互 ​

MySQL ​

MongoDB ​

Redis ​

Valkey ​

Meilisearch ​

Typesense ​

文件存储 ​

运行测试 ​

Laravel Dusk ​

Apple Silicon 上的 Selenium ​

预览电子邮件 ​

容器 CLI ​

PHP 版本 ​

Node 版本 ​

共享您的网站 ​

使用 Xdebug 调试 ​

Linux 主机 IP 配置 ​

Xdebug CLI 使用 ​

Xdebug 浏览器使用 ​

自定义 ​

Laravel Sail

介绍

安装和设置

将 Sail 安装到现有应用程序中

添加额外服务

使用 Devcontainers

重建 Sail 镜像

配置 Shell 别名

启动和停止 Sail

执行命令

执行 PHP 命令

执行 Composer 命令

为现有应用程序安装 Composer 依赖项

执行 Artisan 命令

执行 Node / NPM 命令

与数据库交互

MySQL

MongoDB

Redis

Valkey

Meilisearch

Typesense

文件存储

运行测试

Laravel Dusk

Apple Silicon 上的 Selenium

预览电子邮件

容器 CLI

PHP 版本

Node 版本

共享您的网站

使用 Xdebug 调试

Linux 主机 IP 配置

Xdebug CLI 使用

Xdebug 浏览器使用

自定义