Laravel Sail

简介

Laravel Sail 是一个轻量级的命令行界面，用于与 Laravel 的默认 Docker 开发环境进行交互。Sail 为使用 PHP、MySQL 和 Redis 构建 Laravel 应用提供了一个很好的起点，而无需事先具备 Docker 经验。

从本质上讲，Sail 是存储在项目根目录中的 compose.yaml 文件和 sail 脚本。sail 脚本提供了一个 CLI，包含与 compose.yaml 文件中定义的 Docker 容器进行交互的便捷方法。

Laravel Sail 支持 macOS、Linux 和 Windows（通过 WSL2）。

安装和设置

你可以使用 Composer 包管理器安装 Sail：

shell

composer require laravel/sail --dev

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

shell

php artisan sail:install

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

shell

./vendor/bin/sail up

WARNING

如果你使用的是 Docker Desktop for Linux，应通过执行以下命令使用 default Docker 上下文：docker context use default。此外，如果你在容器内遇到文件权限错误，可能需要将 SUPERVISOR_PHP_USER 环境变量设置为 root。

添加额外服务

如果你想向现有的 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

但是，与其反复输入 vendor/bin/sail 来执行 Sail 命令，你可能希望配置一个 shell 别名，以便更轻松地执行 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 的 compose.yaml 文件定义了各种协同工作的 Docker 容器，以帮助你构建 Laravel 应用。这些容器中的每一个都是 compose.yaml 文件的 services 配置中的一个条目。laravel.test 容器是为你的应用提供服务的主应用容器。

在启动 Sail 之前，你应该确保本地计算机上没有其他 Web 服务器或数据库正在运行。要启动应用的 compose.yaml 文件中定义的所有 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 文档时，你会经常看到不涉及 Sail 的 Composer、Artisan 和 Node / NPM 命令引用。 这些示例假设这些工具已安装在你的本地计算机上。如果你使用 Sail 作为本地 Laravel 开发环境，你应该使用 Sail 执行这些命令：

shell

# 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 版本文档：

shell

sail php --version

sail php script.php

执行 Composer 命令

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

shell

sail composer require laravel/sanctum

执行 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

你可能已经注意到，应用的 compose.yaml 文件包含一个 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 服务，应用的 compose.yaml 文件将包含一个 MongoDB Atlas Local 容器的条目，它提供带有 Atlas 功能（如 Search Indexes）的 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

应用的 compose.yaml 文件还包含一个 Redis 容器的条目。此容器使用 Docker 卷，因此即使在停止和重启容器时，存储在 Redis 实例中的数据也会被持久化。启动容器后，你可以通过将应用的 .env 文件中的 REDIS_HOST 环境变量设置为 redis 来连接到应用中的 Redis 实例。

要从本地机器连接到应用的 Redis 数据库，你可以使用图形化数据库管理应用，例如 TablePlus。默认情况下，Redis 数据库可通过 localhost 端口 6379 访问。

Valkey

如果你在安装 Sail 时选择安装 Valkey 服务，应用的 compose.yaml 文件将包含 Valkey 的条目。此容器使用 Docker 卷，因此即使在停止和重启容器时，存储在 Valkey 实例中的数据也会被持久化。你可以通过将应用的 .env 文件中的 REDIS_HOST 环境变量设置为 valkey 来连接到此容器。

要从本地机器连接到应用的 Valkey 数据库，你可以使用图形化数据库管理应用，例如 TablePlus。默认情况下，Valkey 数据库可通过 localhost 端口 6379 访问。

Meilisearch

如果你在安装 Sail 时选择了安装 Meilisearch 服务，应用的 compose.yaml 文件将包含这个与 Laravel Scout 集成的强大搜索引擎的条目。启动容器后，你可以通过将 MEILISEARCH_HOST 环境变量设置为 http://meilisearch:7700 来连接到应用中的 Meilisearch 实例。

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

Typesense

如果你在安装 Sail 时选择了安装 Typesense 服务，应用的 compose.yaml 文件将包含这个与 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 时安装 RustFS 服务。RustFS 提供了一个 S3 兼容的 API，你可以使用它通过 Laravel 的 s3 文件存储驱动进行本地开发，而无需在生产 S3 环境中创建「测试」存储桶。如果你在安装 Sail 时选择安装 RustFS，RustFS 配置部分将被添加到应用的 compose.yaml 文件中。

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

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://rustfs:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

运行测试

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 或其他工具就可以运行这些测试。要开始使用，取消应用 compose.yaml 文件中 Selenium 服务的注释：

yaml

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

接下来，确保应用的 compose.yaml 文件中的 laravel.test 服务有一个 selenium 的 depends_on 条目：

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 默认的 compose.yaml 文件包含 Mailpit 的服务条目。Mailpit 在本地开发期间拦截应用发送的邮件，并提供一个便捷的 Web 界面，以便你可以在浏览器中预览邮件消息。使用 Sail 时，Mailpit 的默认主机是 mailpit，可通过端口 1025 访问：

ini

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

当 Sail 运行时，你可以通过 http://localhost:8025 访问 Mailpit Web 界面。

如果你在安装 Sail 时选择了 Mailtrap Local 服务，或稍后使用 sail:add Artisan 命令添加了该服务，应用的 compose.yaml 文件会改为包含这个邮件捕获器的配置项。Mailtrap Local 的默认主机为 mailtrap-local，可通过 3535 端口访问：

ini

MAIL_HOST=mailtrap-local
MAIL_PORT=3535

当 Sail 运行时，你可以通过 http://localhost:3550 访问 Mailtrap Local Web 界面。

容器 CLI

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

shell

sail shell

sail root-shell

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

shell

sail tinker

PHP 版本

Sail 目前支持通过 PHP 8.5、8.4、8.3、8.2、8.1 或 PHP 8.0 来提供应用服务。Sail 当前使用的默认 PHP 版本是 PHP 8.5。要更改用于提供应用服务的 PHP 版本，你应该更新应用 compose.yaml 文件中 laravel.test 容器的 build 定义：

yaml

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

# 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 版本。此选项同样在应用的 compose.yaml 文件中定义：

yaml

image: sail-8.2/app

更新应用的 compose.yaml 文件后，你应该重建容器镜像：

shell

sail build --no-cache

sail up

附加 PHP 扩展

Sail 的运行时镜像包含一组常用 PHP 扩展。如果你的应用需要其他扩展，可以在构建镜像时，在应用 compose.yaml 文件中的 laravel.test 服务里添加以空格分隔的 PHP_EXTENSIONS 构建参数：

yaml

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'

更新应用的 compose.yaml 文件后，你应该重建容器镜像。

Node 版本

Sail 默认安装 Node 24。要更改构建镜像时安装的 Node 版本，你可以更新应用 compose.yaml 文件中 laravel.test 服务的 build.args 定义：

yaml

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

更新应用的 compose.yaml 文件后，你应该重建容器镜像：

shell

sail build --no-cache

sail up

有时你可能需要公开分享你的站点，以便向同事展示你的站点或测试应用的 webhook 集成。要分享你的站点，可以使用 share 命令。执行此命令后，你将获得一个随机的 laravel-sail.site URL，你可以用它来访问你的应用：

shell

sail share

通过 share 命令分享站点时，你应该在应用的 bootstrap/app.php 文件中使用 trustProxies middleware 方法配置应用的可信代理。否则，url 和 route 等 URL 生成辅助函数将无法确定 URL 生成期间应使用的正确 HTTP 主机：

php

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

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

shell

sail share --subdomain=my-sail-site

NOTE

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 镜像，以便你对 php.ini 文件的更改生效：

shell

sail 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。要执行此操作，请通过在 compose.yaml 文件中定义自定义网络来为容器配置静态 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 用法

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

shell

# 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 关于零配置调试的文档。

WARNING

Laravel Sail 依赖 artisan serve 来提供应用服务。artisan serve 命令从 Laravel 8.53.0 版本开始才接受 XDEBUG_CONFIG 和 XDEBUG_MODE 变量。旧版本的 Laravel（8.52.0 及以下）不支持这些变量，也不会接受调试连接。

自定义

由于 Sail 本质上就是 Docker，你可以自由地自定义它的几乎所有内容。要发布 Sail 自己的 Dockerfiles，你可以执行 sail:publish 命令：

shell

sail artisan sail:publish

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

shell

sail build --no-cache

Laravel Sail ​

简介 ​

安装和设置 ​

添加额外服务 ​

使用 Devcontainers ​

重建 Sail 镜像 ​

配置 Shell 别名 ​

启动和停止 Sail ​

执行命令 ​

执行 PHP 命令 ​

执行 Composer 命令 ​

执行 Artisan 命令 ​

执行 Node / NPM 命令 ​

与数据库交互 ​

MySQL ​

MongoDB ​

Redis ​

Valkey ​

Meilisearch ​

Typesense ​

文件存储 ​

运行测试 ​

Laravel Dusk ​

Apple Silicon 上的 Selenium ​

预览邮件 ​

容器 CLI ​

PHP 版本 ​

附加 PHP 扩展 ​

Node 版本 ​

分享你的站点 ​

使用 Xdebug 调试 ​

Linux 主机 IP 配置 ​

Xdebug CLI 用法 ​

Xdebug 浏览器用法 ​

自定义 ​

Laravel Sail

简介

安装和设置

添加额外服务

使用 Devcontainers

重建 Sail 镜像

配置 Shell 别名

启动和停止 Sail

执行命令

执行 PHP 命令

执行 Composer 命令

执行 Artisan 命令

执行 Node / NPM 命令

与数据库交互

MySQL

MongoDB

Redis

Valkey

Meilisearch

Typesense

文件存储

运行测试

Laravel Dusk

Apple Silicon 上的 Selenium

预览邮件

容器 CLI

PHP 版本

附加 PHP 扩展

Node 版本

分享你的站点

使用 Xdebug 调试

Linux 主机 IP 配置

Xdebug CLI 用法

Xdebug 浏览器用法

自定义