Laravel 9.x 中文文档

简体中文

English

简体中文

English

主题

Laravel Sail ​

介绍 ​

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

Sail 的核心是存储在项目根目录的 docker-compose.yml 文件和 sail 脚本。sail 脚本提供了一个 CLI，具有方便的方法来与 docker-compose.yml 文件定义的 Docker 容器进行交互。

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

安装与设置 ​

Laravel Sail 会自动安装在所有新的 Laravel 应用程序中，因此您可以立即开始使用它。要了解如何创建新的 Laravel 应用程序，请查阅 Laravel 针对您的操作系统的安装文档。在安装过程中，您将被要求选择应用程序将与哪些 Sail 支持的服务进行交互。

在现有应用中安装 Sail ​

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

shell
composer require laravel/sail --dev

安装 Sail 后，您可以运行 sail:install Artisan 命令。此命令将 Sail 的 docker-compose.yml 文件发布到应用程序的根目录：

shell
php artisan sail:install

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

shell
./vendor/bin/sail up

添加额外服务 ​

如果您想为现有的 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

配置 Shell 别名 ​

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

shell
./vendor/bin/sail up

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

shell
alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

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

一旦配置了 shell 别名，您可以通过简单地输入 sail 来执行 Sail 命令。本文档的其余示例将假设您已配置此别名：

shell
sail up

启动与停止 Sail ​

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

在启动 Sail 之前，您应确保本地计算机上没有其他 Web 服务器或数据库正在运行。要启动应用程序的 docker-compose.yml 文件中定义的所有 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 文档时，您经常会看到引用 Composer、Artisan 和 Node / NPM 命令的示例，这些示例没有引用 Sail。 这些示例假设这些工具已安装在您的本地计算机上。如果您使用 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 2.x 安装：

bash
sail composer require laravel/sanctum

为现有应用安装 Composer 依赖项 ​

如果您与团队一起开发应用程序，您可能不是最初创建 Laravel 应用程序的人。因此，在您将应用程序的存储库克隆到本地计算机后，应用程序的 Composer 依赖项（包括 Sail）都不会被安装。

您可以通过导航到应用程序的目录并执行以下命令来安装应用程序的依赖项。此命令使用一个包含 PHP 和 Composer 的小型 Docker 容器来安装应用程序的依赖项：

shell
docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php82-composer:latest \
    composer install --ignore-platform-reqs

使用 laravelsail/phpXX-composer 镜像时，您应使用计划用于应用程序的 PHP 版本（74、80、81 或 82）。

执行 Artisan 命令 ​

可以使用 artisan 命令执行 Laravel 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 ​

如您所见，应用程序的 docker-compose.yml 文件包含一个 MySQL 容器的条目。此容器使用 Docker 卷，以便即使在停止和重启容器时，存储在数据库中的数据也能持久化。

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

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

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

Redis ​

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

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

MeiliSearch ​

如果您在安装 Sail 时选择安装 MeiliSearch 服务，应用程序的 docker-compose.yml 文件将包含此强大搜索引擎的条目，该引擎与 Laravel Scout 兼容。启动容器后，您可以通过将 MEILISEARCH_HOST 环境变量设置为 http://meilisearch:7700 来连接到应用程序中的 MeiliSearch 实例。

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

文件存储 ​

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

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

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

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

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

您可以通过 MinIO 控制台创建存储桶，该控制台可通过 http://localhost:8900 访问。MinIO 控制台的默认用户名为 sail，默认密码为 password。

WARNING

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

运行测试 ​

Laravel 提供了出色的测试支持，您可以使用 Sail 的 test 命令运行应用程序的功能和单元测试。任何 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 或其他工具的情况下运行这些测试。要开始，请取消注释应用程序的 docker-compose.yml 文件中的 Selenium 服务：

yaml
selenium:
    image: 'selenium/standalone-chrome'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

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

yaml
depends_on:
    - mysql
    - redis
    - selenium

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

shell
sail dusk

Apple Silicon 上的 Selenium ​

如果您的本地计算机包含 Apple Silicon 芯片，您的 selenium 服务必须使用 seleniarm/standalone-chromium 镜像：

yaml
selenium:
    image: 'seleniarm/standalone-chromium'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

预览邮件 ​

Laravel Sail 的默认 docker-compose.yml 文件包含一个 Mailpit 服务条目。Mailpit 拦截应用程序在本地开发期间发送的电子邮件，并提供一个方便的 Web 界面，以便您可以在浏览器中预览电子邮件消息。使用 Sail 时，Mailpit 的默认主机是 mailpit，可通过端口 1025 访问：

ini
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

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

容器 CLI ​

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

shell
sail shell

sail root-shell

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

shell
sail tinker

PHP 版本 ​

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

yaml
# 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

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

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

yaml
image: sail-8.1/app

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

shell
sail build --no-cache

sail up

Node 版本 ​

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

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

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

shell
sail build --no-cache

sail up

分享您的站点 ​

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

shell
sail share

通过 share 命令分享站点时，您应在 TrustProxies 中间件中配置应用程序的受信代理。否则，URL 生成助手（如 url 和 route）将无法确定在 URL 生成期间应使用的正确 HTTP 主机：

php
/**
 * 应用程序的受信代理。
 *
 * @var array|string|null
 */
protected $proxies = '*';

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

shell
sail share --subdomain=my-sail-site

NOTE

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

使用 Xdebug 调试 ​

Laravel Sail 的 Docker 配置支持 Xdebug，这是一个流行且强大的 PHP 调试器。为了启用 Xdebug，您需要在应用程序的 .env 文件中添加一些变量来配置 Xdebug。要启用 Xdebug，您必须在启动 Sail 之前设置适当的模式：

ini
SAIL_XDEBUG_MODE=develop,debug,coverage

Linux 主机 IP 配置 ​

在内部，XDEBUG_CONFIG 环境变量被定义为 client_host=host.docker.internal，以便 Xdebug 为 Mac 和 Windows (WSL2) 正确配置。如果您的本地计算机运行的是 Linux，您应确保运行 Docker Engine 17.06.0+ 和 Compose 1.16.0+。否则，您将需要手动定义此环境变量，如下所示。

首先，您应通过运行以下命令确定要添加到环境变量的正确主机 IP 地址。通常，<container-name> 应为提供应用程序服务的容器的名称，通常以 _laravel.test_1 结尾：

shell
docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>

一旦获得正确的主机 IP 地址，您应在应用程序的 .env 文件中定义 SAIL_XDEBUG_CONFIG 变量：

ini
SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"

Xdebug CLI 使用 ​

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

shell
# 在没有 Xdebug 的情况下运行 Artisan 命令...
sail artisan migrate

# 在有 Xdebug 的情况下运行 Artisan 命令...
sail debug migrate

Xdebug 浏览器使用 ​

要在通过 Web 浏览器与应用程序交互时调试应用程序，请按照 Xdebug 提供的说明启动 Xdebug 会话。

如果您使用的是 PhpStorm，请查看 JetBrain 的有关零配置调试的文档。

WARNING

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

自定义 ​

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

shell
sail artisan sail:publish

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

shell
sail build --no-cache

版权所有 © 2024-2025 laravel.wiki