跳转至内容

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 依赖项。

1composer require laravel/sail --dev

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

1php artisan sail:install

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

1./vendor/bin/sail up

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

添加额外服务

如果你想向现有的 Sail 安装中添加额外服务，可以运行 sail:add Artisan 命令。

1php artisan sail:add

使用开发容器 (Devcontainers)

如果你想在 Devcontainer 中进行开发，可以在 sail:install 命令中提供 --devcontainer 选项。--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 别名

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

1./vendor/bin/sail up

然而，与其重复输入 vendor/bin/sail 来执行 Sail 命令，你可能希望配置一个 shell 别名，以便更轻松地执行 Sail 命令。

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

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

一旦配置了 shell 别名，只需输入 sail 即可执行 Sail 命令。本文档的后续示例将假设你已经配置了这个别名。

1sail up

启动与停止 Sail

Laravel Sail 的 compose.yaml 文件定义了多种协同工作的 Docker 容器，帮助你构建 Laravel 应用程序。这些容器中的每一个都是 compose.yaml 文件 services 配置中的一个条目。laravel.test 容器是负责提供应用程序服务的主容器。

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

1sail up

若要在后台启动所有 Docker 容器，可以以“分离”（detached）模式启动 Sail。

1sail up -d

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

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

1sail stop

执行命令

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

阅读 Laravel 文档时，你经常会看到未提及 Sail 的 Composer、Artisan 和 Node / NPM 命令引用。 这些示例假设这些工具已安装在你的本地计算机上。如果你使用 Sail 作为本地 Laravel 开发环境，则应使用 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

如你所见，应用程序的 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 环境变量以启用身份验证。然后，将凭据添加到连接字符串中。

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

Typesense

如果你在安装 Sail 时选择了安装 Typesense 服务，应用程序的 compose.yaml 文件将包含这个与 Laravel Scout 原生集成的闪电般快速的开源搜索引擎的条目。容器启动后，你可以通过设置以下环境变量来连接到应用程序内的 Typesense 实例。

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

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

文件存储

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

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

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

运行测试

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

1sail test
2 
3sail test --group orders

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

1sail artisan test

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

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

Laravel Dusk

Laravel Dusk 提供了一个富有表现力且易于使用的浏览器自动化和测试 API。得益于 Sail，你无需在本地计算机上安装 Selenium 或其他工具即可运行这些测试。要开始使用，请取消注释应用程序 compose.yaml 文件中的 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

接下来，确保应用程序 compose.yaml 文件中的 laravel.test 服务包含 selenium 的 depends_on 条目。

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

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

当 Sail 运行时，你可以通过以下网址访问 Mailpit Web 界面：https://:8025。

容器 CLI

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

1sail shell
2 
3sail root-shell

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

1sail 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 定义。

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

此外，你可能希望更新 image 名称以反映应用程序正在使用的 PHP 版本。该选项也在应用程序的 compose.yaml 文件中定义。

1image: sail-8.2/app

更新应用程序的 compose.yaml 文件后，应重新构建容器镜像。

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

Node 版本

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

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

更新应用程序的 compose.yaml 文件后，应重新构建容器镜像。

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

共享你的站点

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

1sail share

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

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

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

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

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

使用 Xdebug 调试

Laravel Sail 的 Docker 配置包含对 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 版本，Linux 不支持 host.docker.internal，你需要手动定义主机 IP。为此，请通过在 compose.yaml 文件中定义自定义网络来为容器配置静态 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 使用

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

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 来提供应用程序服务。截至 Laravel 8.53.0 版本，artisan serve 命令仅接受 XDEBUG_CONFIG 和 XDEBUG_MODE 变量。旧版本的 Laravel（8.52.0 及以下）不支持这些变量，也不会接受调试连接。

自定义

由于 Sail 只是 Docker，你可以自由定制其几乎所有内容。要发布 Sail 自带的 Dockerfile，可以执行 sail:publish 命令。

1sail artisan sail:publish

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

1sail build --no-cache

Laravel 是构建、部署和监控软件
 最高效的方式。

产品

Packages

资源

合作伙伴