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 应用结合使用，您可以直接使用 Composer 包管理器安装 Sail。当然，这些步骤假设您现有的本地开发环境允许您安装 Composer 依赖：
composer require laravel/sail --devSail 安装完成后, 您可以运行 sail:install Artisan 命令。此命令会将 Sail 的 compose.yaml 文件发布到您的应用根目录并使用所需环境变量修改您的 .env 文件以便连接到 Docker 服务：
php artisan sail:install最后，您可以启动 Sail。要继续学习如何使用 Sail，请继续阅读本文档的其余部分：
./vendor/bin/sail up[!WARNING]
如果您正在使用适用于 Linux 的 Docker Desktop，您应该使用defaultDocker 上下文，方法是执行以下命令：docker context use default。此外，如果您在容器内遇到文件权限错误，您可能需要将SUPERVISOR_PHP_USER环境变量设置为root。
如果您想为现有的 Sail 安装添加额外服务，您可以运行 sail:add Artisan 命令：
php artisan sail:add如果您想在 开发容器 中进行开发，您可以向 sail:install 命令提供 --devcontainer 选项。该 --devcontainer 选项将指示 sail:install 命令发布一个默认的 .devcontainer/devcontainer.json 文件到您的应用程序根目录：
php artisan sail:install --devcontainer有时，您可能希望完全重建您的 Sail 镜像，以确保镜像的所有包和软件都是最新的。 您可以使用 build 命令来完成此操作：
docker compose down -v
sail build --no-cache
sail up默认情况下，Sail 命令通过包含在所有新的 Laravel 应用程序中的 vendor/bin/sail 脚本被调用：
./vendor/bin/sail up然而，与其反复输入 vendor/bin/sail 来执行 Sail 命令，您可能希望配置一个 shell 别名，以便更轻松地执行 Sail 的命令：
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'为确保此项始终可用，您可将其添加到您的主目录中的 shell 配置文件，例如 ~/.zshrc 或 ~/.bashrc，然后重启您的 shell。
一旦 shell 别名配置完毕，您只需输入 sail 即可执行 Sail 命令. 本文档其余部分的示例将假定您已配置此别名:
sail upLaravel Sail 的 compose.yaml 文件定义了各种 Docker 容器，它们协同工作以帮助你构建 Laravel 应用程序。每个容器都是你的 compose.yaml 文件 services 配置中的一个条目。laravel.test 容器是主要的应用程序容器，它将为你的应用程序提供服务。
在启动 Sail 之前，您应该确保没有其他 Web 服务器或数据库正在您的本地计算机上运行。要启动您应用程序的 compose.yaml 文件中定义的所有 Docker 容器，您应该执行 up 命令：
sail up为了在后台启动所有 Docker 容器，你可以以“分离”模式启动 Sail：
sail up -d一旦应用程序的容器已启动，您可以在Web浏览器中访问项目，地址为：http://localhost。
要停止所有容器，只需按下 Control + C 即可停止容器的执行。或者，如果容器在后台运行，您可以使用 stop 命令：
sail stop当使用 Laravel Sail 时，你的应用程序正在 Docker 容器中执行，并与你的本地计算机隔离。然而，Sail 提供了一种便捷的方式来针对你的应用程序运行各种命令，例如任意的 PHP 命令、Artisan 命令、Composer 命令以及 Node / NPM 命令。
阅读 Laravel 文档时，你经常会看到对不提及 Sail 的 Composer、Artisan 和 Node / NPM 命令的引用。 那些示例假设这些工具已安装在你的本地计算机上。如果你正在使用 Sail 作为你的本地 Laravel 开发环境，你应该使用 Sail 执行那些命令：
# Running Artisan commands locally...
php artisan queue:work
# Running Artisan commands within Laravel Sail...
sail artisan queue:workPHP 命令可以使用 php 命令来执行。当然，这些命令将使用为你的应用配置的 PHP 版本来执行。要了解更多关于 Laravel Sail 可用的 PHP 版本，请查阅 PHP 版本文档：
sail php --version
sail php script.phpComposer 命令可以使用 composer 命令执行。Laravel Sail 的应用容器包含 Composer 安装：
sail composer require laravel/sanctumLaravel Artisan 命令可以使用 artisan 命令执行：
sail artisan queue:workNode 命令可以使用 node 命令执行，而 NPM 命令可以使用 npm 命令执行:
sail node --version
sail npm run dev如果您愿意，您可以使用 Yarn 而不是 NPM：
sail yarn您可能已经注意到，您的应用程序的 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 环境变量的值作为其密码。
如果您选择在安装 Sail 时安装 MongoDB 服务，您的应用程序的 compose.yaml 文件包含一个 MongoDB Atlas 本地容器的条目，该容器提供带有 Atlas 功能的 MongoDB 文档数据库，例如 搜索索引。此容器使用 Docker 卷，以便即使在停止和重新启动容器时，存储在数据库中的数据也能持久化。
一旦你启动了容器，你就可以通过将应用程序的 .env 文件中的 MONGODB_URI 环境变量设置为 mongodb://mongodb:27017 来连接到应用程序中的 MongoDB 实例. 身份验证默认是禁用的，但你可以在启动 mongodb 容器之前，设置 MONGODB_USERNAME 和 MONGODB_PASSWORD 环境变量来启用身份验证. 然后，将凭据添加到连接字符串:
MONGODB_USERNAME=user
MONGODB_PASSWORD=laravel
MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017为了将 MongoDB 与您的应用程序无缝集成，您可以安装由 MongoDB 维护的官方包。
要从本地机器连接到应用程序的 MongoDB 数据库，您可以使用图形界面工具，例如 Compass。默认情况下，MongoDB 数据库可通过 localhost 端口 27017 访问。
您的应用程序的compose.yaml文件也包含一个Redis容器的条目。这个容器使用一个Docker 卷，以便存储在您的 Redis 实例中的数据即使在停止和重新启动容器时也能持久化。一旦您启动了容器，您可以通过在您的应用程序的.env文件中将REDIS_HOST环境变量设置为redis来连接到应用程序内的 Redis 实例。
从本地机器连接到您的应用程序的 Redis 数据库，您可以使用图形化数据库管理应用程序，例如 TablePlus。默认情况下，Redis 数据库可通过 localhost 端口 6379 访问。
如果您选择在安装 Sail 时安装 Valkey 服务，您的应用程序的 compose.yaml 文件将包含一个用于 Valkey 的条目。此容器使用 Docker volume，以便即使在停止和重新启动容器时，存储在 Valkey 实例中的数据也能持久化。您可以在应用程序中连接到此容器，方法是将您应用程序的 .env 文件中的 REDIS_HOST 环境变量设置为 valkey。
要从本地机器连接到您的应用程序的Valkey数据库，您可以使用图形化数据库管理应用程序，例如TablePlus。默认情况下，Valkey数据库可在localhost端口6379访问。
如果你选择在安装 Sail 时安装 Meilisearch 服务，你的应用程序的 compose.yaml 文件将包含此强大搜索引擎的条目，它与 Laravel Scout 集成。一旦你启动了容器，你可以在你的应用程序中通过将你的 MEILISEARCH_HOST 环境变量设置为 http://meilisearch:7700 来连接 Meilisearch 实例。
在您的本地机器上，您可以通过在 Web 浏览器中导航到 http://localhost:7700 来访问 Meilisearch 基于 Web 的管理面板。
如果您选择在安装 Sail 时安装 Typesense 服务，您的应用程序的 compose.yaml 文件将包含一个针对此闪电般快速、原生集成 Laravel Scout 的开源搜索引擎的条目。启动容器后，您可以通过设置以下环境变量，连接到应用程序内的 Typesense 实例：
TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz从您的本地机器，您可以访问 Typesense 的 API 通过 http://localhost:8108。
如果你计划在生产环境运行应用程序时使用 Amazon S3 存储文件，你可能希望在安装 Sail 时安装 MinIO 服务。MinIO 提供了一个 S3 兼容的 API，你可以用它在使用 Laravel 的 s3 文件存储驱动程序进行本地开发时，而无需在你的生产 S3 环境中创建“测试”存储桶。如果你选择在安装 Sail 时安装 MinIO，MinIO 配置部分将被添加到你的应用程序的 compose.yaml 文件中。
默认情况下，你的应用的 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.
[!警告]
通过temporaryUrl方法生成临时存储 URL 在使用 MinIO 时不受支持。
Laravel 开箱即用，提供了出色的测试支持，您可以使用 Sail 的 test 命令来运行您的应用程序的 功能测试和单元测试。任何 Pest / PHPUnit 接受的 CLI 选项也可以传递给 test 命令：
sail test
sail test --group ordersSail test 命令等同于运行 test Artisan 命令：
sail artisan test默认情况下，Sail 将创建一个专门的 testing 数据库，以便您的测试不会干扰您的数据库的当前状态。在默认的 Laravel 安装中，Sail 还会配置您的 phpunit.xml 文件，以便在执行测试时使用此数据库：
<env name="DB_DATABASE" value="testing"/>[Laravel Dusk](/zh-cn/docs/laravel/12.x/dusk) 提供了富有表现力且易于使用的浏览器自动化和测试 API。得益于 Sail，你无需在本地计算机上安装 Selenium 或其他工具即可运行这些测试。要开始使用，请在你的应用程序的compose.yaml文件中取消对 Selenium 服务的注释：
selenium:
image: 'selenium/standalone-chrome'
extra_hosts:
- 'host.docker.internal:host-gateway'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sail接下来，确保在你的应用程序的 compose.yaml 文件中，laravel.test 服务有一个 depends_on 条目指向 selenium：
depends_on:
- mysql
- redis
- selenium最后，您可以通过启动 Sail 并运行 dusk 命令来运行您的 Dusk 测试套件：
sail dusk如果您的本地机器包含 Apple Silicon 芯片，您的 selenium 服务必须使用 selenium/standalone-chromium 镜像：
selenium:
image: 'selenium/standalone-chromium'
extra_hosts:
- 'host.docker.internal:host-gateway'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sailLaravel Sail 的默认 compose.yaml 文件包含 Mailpit 的服务条目。Mailpit 会在本地开发期间拦截你的应用程序发送的电子邮件，并提供一个方便的网页界面，以便你可以在浏览器中预览你的电子邮件消息。当使用 Sail 时，Mailpit 的默认主机是 mailpit，可通过端口 1025 访问：
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null当 Sail 运行时，您可以通过以下地址访问 Mailpit 网页界面：http://localhost:8025
有时您可能希望在您的应用程序容器内启动一个 Bash 会话。您可以使用 shell 命令连接到您的应用程序容器，从而允许您检查其文件和已安装的服务，以及在容器内执行任意 shell 命令：
sail shell
sail root-shell要启动一个新的 Laravel Tinker 会话，你可以执行 tinker 命令：
sail tinkerSail 目前支持通过 PHP 8.4、8.3、8.2、8.1 或 PHP 8.0 来为你的应用提供服务。Sail 当前使用的默认 PHP 版本是 PHP 8.4。要更改用于为你的应用提供服务的 PHP 版本，你应该更新你应用中 compose.yaml 文件里 laravel.test 容器的 build 定义：
# 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 文件中：
image: sail-8.2/app更新你的应用程序的compose.yaml文件后，你应该重建你的容器镜像：
sail build --no-cache
sail upSail 默认安装 Node 22。要更改构建镜像时安装的 Node 版本，你可以在应用程序的 compose.yaml 文件中更新 laravel.test 服务的 build.args 定义：
build:
args:
WWWGROUP: '${WWWGROUP}'
NODE_VERSION: '18'在更新你的应用程序的compose.yaml文件之后，你应当重建你的容器镜像：
sail build --no-cache
sail up有时您可能需要公开分享您的站点，以便让同事预览您的站点，或测试您的应用程序与 Webhook 的集成。要分享您的站点，您可以使用share命令。执行此命令后，您将获得一个随机的laravel-sail.siteURL，您可以使用它来访问您的应用程序：
sail share当通过 share 命令共享您的站点时，您应该在应用程序的 bootstrap/app.php 文件中，使用 trustProxies 中间件方法来配置应用程序的受信任代理。否则，诸如 url 和 route 等 URL 生成助手将无法确定在 URL 生成期间应使用的正确 HTTP 主机：
->withMiddleware(function (Middleware $middleware): void {
$middleware->trustProxies(at: '*');
})如果您想为共享站点选择子域名，您可以在执行 share 命令时提供 subdomain 选项：
sail share --subdomain=my-sail-site[!注意]
该share命令由 Expose 提供支持，一项由 BeyondCode 提供的开源隧道服务。
Laravel Sail 的 Docker 配置包含对 Xdebug 的支持，它是一个流行且功能强大的 PHP 调试器。要启用 Xdebug，请确保你已 发布你的 Sail 配置。然后，将以下变量添加到你的应用程序的 .env 文件中以配置 Xdebug：
SAIL_XDEBUG_MODE=develop,debug,coverage接下来，请确保您已发布的 php.ini 文件包含以下配置，以便 Xdebug 在指定模式下激活：
[xdebug]
xdebug.mode=${XDEBUG_MODE}修改 php.ini 文件后，请记住重建您的 Docker 镜像，以使您对 php.ini 文件的更改生效：
sail build --no-cache内部，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：
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"一个 sail debug 命令可用于在运行 Artisan 命令时启动调试会话：
# Run an Artisan command without Xdebug...
sail artisan migrate
# Run an Artisan command with Xdebug...
sail debug migrate在通过网络浏览器与应用程序交互时调试您的应用程序，请遵循 Xdebug 提供的说明，以从网络浏览器发起 Xdebug 会话。
如果您正在使用 PhpStorm，请查阅 JetBrains 的文档，了解 零配置调试。
[!WARNING]
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 安装后，您可能希望更改应用程序容器的镜像名称，在您应用程序的 compose.yaml 文件中。完成此操作后，使用 build 命令重建应用程序的容器。为应用程序镜像分配唯一名称特别重要，如果您在同一台机器上使用 Sail 开发多个 Laravel 应用程序：
sail build --no-cache