后盾人

Appearance

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 文件发布到应用程序的根目录,并修改 .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。

添加额外的服务 ​

如果你想向现有的 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 的 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 安装:

php
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/php83-composer:latest \
    composer install --ignore-platform-reqs

使用 laravelsail/phpXX-composer 镜像时,你应该使用与你计划用于应用程序相同版本的 PHP(80、81、82 或 83)。

执行 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 ​

你可能已经注意到,你的应用程序的 docker-compose.yml 文件包含一个 MySQL 容器的条目。这个容器使用 Docker volume,以便即使在停止和重新启动容器时,存储在数据库中的数据也能持久保存。

此外,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 volume,以便即使在停止和重新启动容器时,存储在 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 的管理面板。

Typesense ​

如果你在安装 Sail 时选择安装 Typesense 服务,你的应用程序的 docker-compose.yml 文件将包含这个闪电般快速的开源搜索引擎的条目,该引擎与 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 时安装 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

为了使 Laravel 的 Flysystem 集成在使用 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 命令来运行你的应用程序的功能和单元测试。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 或其他工具。要开始使用,请取消注释应用程序的 docker-compose.yml 文件中的 Selenium 服务:

yaml
selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    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 服务必须使用 selenium/standalone-chromium 映像:

yaml
selenium:
    image: 'seleniarm/standalone-chromium'
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    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 运行时，您可以通过以下方式访问 Mailpit Web 界面: http://localhost:8025

容器命令 ​

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

shell
sail shell

sail root-shell

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

shell
sail tinker

PHP 版本 ​

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

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

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

yaml
image: sail-8.2/app

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

shell
sail build --no-cache

sail up

Node 版本 ​

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

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

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

shell
sail build --no-cache

sail up

共享您的网站 ​

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

shell
sail share

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

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

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

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

NOTE

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

使用 Xdebug 进行调试 ​

Laravel Sail 的 Docker 配置包括对 Xdebug 的支持，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 20.10+，则 host.docker.internal 可用，无需手动配置。

对于早于 20.10 的 Docker 版本，Linux 不支持 host.docker.internal，您需要手动定义主机 IP。为此，请通过在 docker-compose.yml 文件中定义自定义网络来为容器配置静态 IP:

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 用法 ​

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

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

#使用 Xdebug 运行 Artisan 命令...
sail debug migrate

Xdebug 浏览器使用 ​

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

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

WARNING

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

定制 ​

由于 Sail 只是 Docker，因此您可以自由自定义几乎所有相关信息。要发布 Sail 自己的 Dockerfile，您可以执行 sail:publish 命令:

shell
sail artisan sail:publish

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

shell
sail build --no-cache

后盾人版权所有 © 2018-2025 创作不易请尊重他人劳动成果，未经授权禁止转载！