跳至内容

Laravel Sail

介绍

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

Sail 的核心是存储在项目根目录下的docker-compose.yml文件和脚本。该脚本提供了一个 CLI，其中包含与文件定义的 Docker 容器交互的便捷方法。sailsaildocker-compose.yml

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

安装和设置

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

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

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

1composer require laravel/sail --dev

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

1php artisan sail:install

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

1./vendor/bin/sail up

如果您正在使用适用于 Linux 的 Docker Desktop，则应default通过执行以下命令来使用 Docker 上下文：docker context use default。

添加附加服务

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

1php artisan sail:add

使用 Devcontainers

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

1php artisan sail:install --devcontainer

重建Sail船图像

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

1docker compose down -v
2 
3sail build --no-cache
4 
5sail up

配置 Shell 别名

vendor/bin/sail默认情况下，使用所有新 Laravel 应用程序附带的脚本调用 Sail 命令：

1./vendor/bin/sail up

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

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

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

配置好 shell 别名后，只需输入 即可执行 Sail 命令sail。本文档的其余示例都假定您已配置此别名：

1sail up

启航和停航

Laravel Sail 的docker-compose.yml文件定义了各种 Docker 容器，它们协同工作以帮助您构建 Laravel 应用程序。每个容器都是文件services配置中的一个条目docker-compose.yml。laravel.test容器是将为您的应用程序提供服务的主要应用程序容器。

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

1sail up

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

1sail up -d

应用程序的容器启动后，您可以通过 Web 浏览器访问该项目：http://localhost。

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

1sail stop

执行命令

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

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

1# Running Artisan commands locally...
2php artisan queue:work
3 
4# Running Artisan commands within Laravel Sail...
5sail artisan queue:work

执行 PHP 命令

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

1sail php --version
2 
3sail php script.php

执行 Composer 命令

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

1sail composer require laravel/sanctum

执行 Artisan 命令

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

1sail artisan queue:work

执行 Node / NPM 命令

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

1sail node --version
2 
3sail npm run dev

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

1sail yarn

与数据库交互

MySQL

你可能已经注意到，你的应用程序docker-compose.yml文件包含一个 MySQL 容器的条目。该容器使用Docker 卷，这样即使停止并重新启动容器，数据库中存储的数据也会保留下来。

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

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

要从本地计算机连接到应用程序的 MySQL 数据库，您可以使用图形数据库管理应用程序（例如TablePlus ）。默认情况下，MySQL 数据库可通过端口 3306 访问，访问凭据与localhost您的环境变量值相对应。或者，您可以以用户身份连接，这也会使用环境变量的值作为密码。DB_USERNAMEDB_PASSWORDrootDB_PASSWORD

MongoDB

如果您在安装 Sail 时选择安装MongoDB服务，则应用程序文件将包含一个MongoDB Atlas Localdocker-compose.yml容器的条目，该容器为 MongoDB 文档数据库提供 Atlas 功能，例如搜索索引。此容器使用Docker 卷，以便即使在停止和重新启动容器时，存储在数据库中的数据也会保留下来。

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

1MONGODB_USERNAME=user
2MONGODB_PASSWORD=laravel
3MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017

为了将 MongoDB 与您的应用程序无缝集成，您可以安装MongoDB 维护的官方包。

要从本地计算机连接到应用程序的 MongoDB 数据库，可以使用图形界面（例如Compass ）localhost 。默认情况下，可以通过端口访问 MongoDB 数据库27017。

Redis

您的应用程序文件还包含一个Redisdocker-compose.yml容器的条目。此容器使用Docker 卷，因此即使停止并重新启动容器，存储在 Redis 实例中的数据也会保留下来。启动容器后，您可以通过将应用程序文件中的环境变量设置为 来连接到应用程序中的 Redis 实例。REDIS_HOST.envredis

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

瓦尔基

如果您在安装 Sail 时选择安装 Valkey 服务，则应用程序文件将包含Valkeydocker-compose.yml的条目。此容器使用Docker 卷，以便即使在停止和重新启动容器时，存储在 Valkey 实例中的数据也能保留。您可以通过将应用程序文件中的环境变量设置为 来连接到此容器。REDIS_HOST.envvalkey

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

美丽搜索

如果您在安装 Sail 时选择安装Meil​​isearch服务，您的应用程序文件将包含一个与Laravel Scoutdocker-compose.yml集成的强大搜索引擎的条目。启动容器后，您可以通过将环境变量设置为 来连接到应用程序中的 Meil​​isearch 实例。MEILISEARCH_HOSThttp://meilisearch:7700

您可以从本地计算机通过http://localhost:7700Web 浏览器访问 Meil​​isearch 的基于 Web 的管理面板。

Typesense

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

1TYPESENSE_HOST=typesense
2TYPESENSE_PORT=8108
3TYPESENSE_PROTOCOL=http
4TYPESENSE_API_KEY=xyz

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

文件存储

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

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

1FILESYSTEM_DISK=s3
2AWS_ACCESS_KEY_ID=sail
3AWS_SECRET_ACCESS_KEY=password
4AWS_DEFAULT_REGION=us-east-1
5AWS_BUCKET=local
6AWS_ENDPOINT=http://minio:9000
7AWS_USE_PATH_STYLE_ENDPOINT=true

为了使 Laravel 的 Flysystem 集成在使用 MinIO 时生成正确的 URL，您应该定义AWS_URL环境变量，使其与应用程序的本地 URL 匹配，并在 URL 路径中包含存储桶名称：

1AWS_URL=http://localhost:9000/local

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

temporaryUrl使用 MinIO 时不支持 通过该方法生成临时存储 URL 。

运行测试

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

1sail test
2 
3sail test --group orders

Sailtest命令相当于运行testArtisan 命令：

1sail artisan test

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

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

Laravel Dusk

Laravel Dusk提供了一套简洁易用的浏览器自动化测试 API。借助 Sail，您无需在本地计算机上安装 Selenium 或其他工具即可运行这些测试。首先，在应用程序docker-compose.yml文件中取消注释 Selenium 服务：

1selenium:
2    image: 'selenium/standalone-chrome'
3    extra_hosts:
4      - 'host.docker.internal:host-gateway'
5    volumes:
6        - '/dev/shm:/dev/shm'
7    networks:
8        - sail

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

1depends_on:
2    - mysql
3    - redis
4    - selenium

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

1sail dusk

Apple Silicon 上的 Selenium

如果您的本地机器包含 Apple Silicon 芯片，则您的selenium服务必须使用以下selenium/standalone-chromium映像：

1selenium:
2    image: 'selenium/standalone-chromium'
3    extra_hosts:
4        - 'host.docker.internal:host-gateway'
5    volumes:
6        - '/dev/shm:/dev/shm'
7    networks:
8        - sail

预览电子邮件

Laravel Sail 的默认文件包含Mailpitdocker-compose.yml的服务入口。Mailpit 会在本地开发期间拦截应用程序发送的邮件，并提供便捷的 Web 界面，方便您在浏览器中预览邮件内容。使用 Sail 时，Mailpit 的默认主机是，可通过端口 1025 访问：mailpit

1MAIL_HOST=mailpit
2MAIL_PORT=1025
3MAIL_ENCRYPTION=null

当 Sail 运行时，您可以通过以下网址访问 Mailpit 网页界面：http://localhost:8025

容器 CLI

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

1sail shell
2 
3sail root-shell

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

1sail tinker

PHP 版本

Sail 目前支持通过 PHP 8.4、8.3、8.2、8.1 或 PHP 8.0 为您的应用程序提供服务。Sail 默认使用的 PHP 版本是 PHP 8.4。要更改用于服务应用程序的 PHP 版本，您需要更新应用程序文件中容器build的定义：laravel.testdocker-compose.yml

 1# PHP 8.4
 2context: ./vendor/laravel/sail/runtimes/8.4
 3 
 4# PHP 8.3
 5context: ./vendor/laravel/sail/runtimes/8.3
 6 
 7# PHP 8.2
 8context: ./vendor/laravel/sail/runtimes/8.2
 9 
10# PHP 8.1
11context: ./vendor/laravel/sail/runtimes/8.1
12 
13# PHP 8.0
14context: ./vendor/laravel/sail/runtimes/8.0

此外，您可能希望更新您的image名称，以反映应用程序所使用的 PHP 版本。此选项也定义在您的应用程序docker-compose.yml文件中：

1image: sail-8.2/app

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

1sail build --no-cache
2 
3sail up

Node 版本

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

1build:
2    args:
3        WWWGROUP: '${WWWGROUP}'
4        NODE_VERSION: '18'

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

1sail build --no-cache
2 
3sail up

共享您的网站

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

1sail share

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

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

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

1sail share --subdomain=my-sail-site

该命令由BeyondCode的开源隧道服务Exposeshare提供支持。

使用 Xdebug 进行调试

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

1SAIL_XDEBUG_MODE=develop,debug,coverage

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

1[xdebug]
2xdebug.mode=${XDEBUG_MODE}

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

1sail build --no-cache

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.internalLinux 上不支持，您需要手动定义主机 IP。为此，请在docker-compose.yml文件中定义自定义网络，为容器配置静态 IP：

 1networks:
 2  custom_network:
 3    ipam:
 4      config:
 5        - subnet: 172.20.0.0/16
 6 
 7services:
 8  laravel.test:
 9    networks:
10      custom_network:
11        ipv4_address: 172.20.0.2

设置静态 IP 后，在应用程序的 .env 文件中定义 SAIL_XDEBUG_CONFIG 变量：

1SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Xdebug CLI 使用

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

1# Run an Artisan command without Xdebug...
2sail artisan migrate
3 
4# Run an Artisan command with Xdebug...
5sail 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命令：

1sail artisan sail:publish

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

1sail build --no-cache