Laravel 13.x 中文文档

主题

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）。

安装和设置 ​

Laravel Sail 会随所有新的 Laravel 应用程序自动安装，因此您可以立即开始使用它。

在现有应用程序中安装 Sail ​

如果您有兴趣在现有 Laravel 应用程序中使用 Sail，可以简单地使用 Composer 包管理器安装 Sail。当然，这些步骤假设您现有的本地开发环境允许您安装 Composer 依赖项：

shell
composer require laravel/sail --dev

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

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
# 本地运行 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

执行 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 功能（如搜索索引）的 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 运行时，您可以在以下地址访问 Mailpit Web 界面：http://localhost:8025

容器 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

Node 版本 ​

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

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

共享您的站点 ​

有时您可能需要与同事或客户共享您的站点预览。为此，您可以使用 share 命令：

shell
sail share

此命令将生成一个可以与任何人共享的随机 URL。他们可以使用此 URL访问您的应用程序。

使用 Xdebug 调试 ​

Laravel Sail 包含对 Xdebug 的支持，这是一个流行且强大的 PHP 调试器。要启用 Xdebug，您需要在应用程序的 .env 文件中设置 SAIL_XDEBUG_MODE 环境变量：

ini
SAIL_XDEBUG_MODE=develop,debug,coverage

您可以在 Xdebug 文档 中了解有关 Xdebug 模式的更多信息。

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。为此，通过在 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 用法 ​

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

shell
# 不使用 Xdebug 运行 Artisan 命令...
sail artisan migrate

# 使用 Xdebug 运行 Artisan 命令...
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 自己的 Dockerfile，您可以执行 sail:publish 命令：

shell
sail artisan sail:publish

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

shell
sail build --no-cache