Laravel 中文文档

主题

全部文档

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 应用都会自动安装 Laravel Sail，因此你可以立即开始使用。

在现有应用中安装 Sail ​

若希望在现有 Laravel 应用中使用 Sail，只需用 Composer 安装即可。当然，这些步骤假定你现有的本地开发环境允许安装 Composer 依赖：

shell
composer require laravel/sail --dev

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

shell
php artisan sail:install

最后可启动 Sail。要继续了解用法，请阅读本文档其余部分：

shell
./vendor/bin/sail up

WARNING

若使用 Linux 版 Docker Desktop，应执行 docker context use default 使用 default Docker context。此外，若在容器内遇到文件权限错误，可能需要将 SUPERVISOR_PHP_USER 环境变量设为 root。

添加额外服务 ​

若要向现有 Sail 安装添加额外服务，可运行 sail:add Artisan 命令：

shell
php artisan sail:add

使用 Devcontainer ​

若希望在 Devcontainer 中开发，可为 sail:install 提供 --devcontainer 选项，以将默认 .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，你可能希望配置 shell 别名以便更轻松地执行 Sail 命令：

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

为确保始终可用，可将其加入主目录的 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc），然后重启 shell。

配置别名后，只需输入 sail 即可执行 Sail 命令。本文档其余示例均假定已配置该别名：

shell
sail up

启动与停止 Sail ​

Laravel Sail 的 compose.yaml 定义了多种协同工作的 Docker 容器以帮助构建 Laravel 应用。每个容器是 compose.yaml 中 services 配置的一项。laravel.test 是提供应用服务的主应用容器。

启动 Sail 前，应确保本机没有其他 Web 服务器或数据库在运行。要启动应用 compose.yaml 中定义的所有 Docker 容器，应执行 up 命令：

shell
sail up

若要在后台启动所有 Docker 容器，可以「detached」模式启动 Sail：

shell
sail up -d

应用容器启动后，可在浏览器访问：http://localhost。

要停止所有容器，可按 Control + C。若容器在后台运行，可使用 stop 命令：

shell
sail stop

执行命令 ​

使用 Laravel Sail 时，应用在 Docker 容器中运行并与本机隔离。但 Sail 提供便捷方式对应用运行各种命令，例如任意 PHP、Artisan、Composer 以及 Node / NPM 命令。

阅读 Laravel 文档时，常会看到未提及 Sail 的 Composer、Artisan 与 Node / NPM 命令。 那些示例假定这些工具已安装在本机。若使用 Sail 作为本地 Laravel 开发环境，应通过 Sail 执行这些命令：

shell
# Running Artisan commands locally...
php artisan queue:work

# Running Artisan commands within Laravel Sail...
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：

shell
sail composer require laravel/sanctum

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

如你所见，应用的 compose.yaml 包含 MySQL 容器条目。该容器使用 Docker volume，以便在停止并重启容器后仍保留数据库数据。

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

容器启动后，可将应用 .env 中的 DB_HOST 设为 mysql，以在应用内连接 MySQL 实例。

要从本机连接应用的 MySQL 数据库，可使用 TablePlus 等图形化数据库管理工具。默认可通过 localhost 的 3306 端口访问，凭据对应 DB_USERNAME 与 DB_PASSWORD。也可使用 root 用户连接，其密码同样使用 DB_PASSWORD 的值。

MongoDB ​

若在安装 Sail 时选择安装 MongoDB 服务，应用的 compose.yaml 会包含 MongoDB Atlas Local 容器条目，提供带有 Search Indexes 等 Atlas 特性的 MongoDB 文档数据库。该容器使用 Docker volume 持久化数据。

容器启动后，可将 .env 中的 MONGODB_URI 设为 mongodb://mongodb:27017 以在应用内连接。默认禁用认证，但可在启动 mongodb 容器前设置 MONGODB_USERNAME 与 MONGODB_PASSWORD 启用认证，并将凭据加入连接字符串：

ini
MONGODB_USERNAME=user
MONGODB_PASSWORD=laravel
MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017

为与应用无缝集成 MongoDB，可安装 MongoDB 官方维护的包。

要从本机连接，可使用 Compass 等图形界面。默认可通过 localhost 的 27017 端口访问。

Redis ​

应用的 compose.yaml 也包含 Redis 容器条目，并使用 Docker volume 持久化数据。容器启动后，可将 .env 中的 REDIS_HOST 设为 redis 以在应用内连接。

要从本机连接，可使用 TablePlus 等工具。默认可通过 localhost 的 6379 端口访问。

Valkey ​

若在安装 Sail 时选择安装 Valkey，compose.yaml 会包含 Valkey 条目，并使用 Docker volume 持久化数据。可将 .env 中的 REDIS_HOST 设为 valkey 以在应用内连接。

要从本机连接，可使用 TablePlus 等工具。默认可通过 localhost 的 6379 端口访问。

Meilisearch ​

若在安装 Sail 时选择安装 Meilisearch，compose.yaml 会包含该搜索引擎条目，并与 Laravel Scout 集成。容器启动后，可将 MEILISEARCH_HOST 设为 http://meilisearch:7700 以在应用内连接。

在本机可通过浏览器访问 http://localhost:7700 打开 Meilisearch 的 Web 管理面板。

Typesense ​

若在安装 Sail 时选择安装 Typesense，compose.yaml 会包含该开源搜索引擎条目，并与 Laravel Scout 原生集成。容器启动后，可通过设置以下环境变量在应用内连接：

ini
TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz

在本机可通过 http://localhost:8108 访问 Typesense API。

文件存储 ​

若生产环境计划用 Amazon S3 存储文件，安装 Sail 时可能希望安装 RustFS 服务。RustFS 提供兼容 S3 的 API，便于本地使用 Laravel 的 s3 文件存储驱动开发，而无需在生产 S3 环境创建「测试」存储桶。若安装 Sail 时选择 RustFS，会在 compose.yaml 中加入相应配置。

默认情况下，应用的 filesystems 配置已包含 s3 磁盘。除与 Amazon S3 交互外，也可通过修改相关环境变量与任何兼容 S3 的存储服务（如 RustFS）交互。例如使用 RustFS 时，文件系统环境变量可如下配置：

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

运行测试 ​

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 或其他工具即可运行这些测试。开始时请取消注释应用 compose.yaml 中的 Selenium 服务：

yaml
selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

接着确保应用 compose.yaml 中的 laravel.test 服务对 selenium 有 depends_on 条目：

yaml
depends_on:
    - mysql
    - redis
    - selenium

最后，启动 Sail 并运行 dusk 命令即可执行 Dusk 测试套件：

shell
sail dusk

在 Apple Silicon 上使用 Selenium ​

若本机使用 Apple Silicon 芯片，selenium 服务必须使用 selenium/standalone-chromium 镜像：

yaml
selenium:
    image: 'selenium/standalone-chromium'
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

预览邮件 ​

Laravel Sail 默认的 compose.yaml 包含 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.5、8.4、8.3、8.2、8.1 或 PHP 8.0 提供应用服务。当前默认 PHP 版本为 PHP 8.5。要更改用于提供应用服务的 PHP 版本，应更新应用 compose.yaml 中 laravel.test 容器的 build 定义：

yaml
# PHP 8.5
context: ./vendor/laravel/sail/runtimes/8.5

# 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 中定义：

yaml
image: sail-8.2/app

更新 compose.yaml 后，应重建容器镜像：

shell
sail build --no-cache

sail up

Node 版本 ​

Sail 默认安装 Node 22。要更改构建镜像时安装的 Node 版本，可更新 laravel.test 服务的 build.args 定义：

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

更新 compose.yaml 后，应重建容器镜像：

shell
sail build --no-cache

sail up

分享站点 ​

有时你可能需要公开分享站点，以便同事预览或测试 webhook 集成。可使用 share 命令；执行后会获得一个随机的 laravel-sail.site URL 用于访问应用：

shell
sail share

通过 share 分享站点时，应在 bootstrap/app.php 中用 trustProxies 中间件方法配置可信代理。否则 url、route 等 URL 生成辅助函数将无法确定生成 URL 时应使用的正确 HTTP host：

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

若要为分享站点选择子域名，可在执行 share 时提供 subdomain 选项：

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

INFO

share 命令由 BeyondCode 的开源隧道服务 Expose 驱动。

使用 Xdebug 调试 ​

Laravel Sail 的 Docker 配置支持流行且强大的 PHP 调试器 Xdebug。要启用 Xdebug，请确保已发布 Sail 配置，然后在应用 .env 中加入以下变量：

ini
SAIL_XDEBUG_MODE=develop,debug,coverage

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

ini
[xdebug]
xdebug.mode=${XDEBUG_MODE}

修改 php.ini 后，请记得重建 Docker 镜像以使更改生效：

shell
sail build --no-cache

Linux 主机 IP 配置 ​

内部会将 XDEBUG_CONFIG 环境变量定义为 client_host=host.docker.internal，以便在 Mac 与 Windows（WSL2）上正确配置 Xdebug。若本机运行 Linux 且使用 Docker 20.10+，则 host.docker.internal 可用，无需手动配置。

对于早于 20.10 的 Docker 版本，Linux 不支持 host.docker.internal，需手动定义主机 IP。可在 compose.yaml 中定义自定义网络，为容器配置静态 IP：

yaml
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 变量：

ini
SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Xdebug CLI 用法 ​

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

shell
# Run an Artisan command without Xdebug...
sail artisan migrate

# Run an Artisan command with Xdebug...
sail debug migrate

Xdebug 浏览器用法 ​

要通过 Web 浏览器与应用交互时进行调试，请遵循 Xdebug 提供的说明，从浏览器发起 Xdebug 会话。

若使用 PhpStorm，请参阅 JetBrains 关于零配置调试的文档。

WARNING

Laravel Sail 依赖 artisan serve 提供应用服务。自 Laravel 8.53.0 起，artisan serve 才接受 XDEBUG_CONFIG 与 XDEBUG_MODE 变量。更旧的版本（8.52.0 及以下）不支持这些变量，也不会接受调试连接。

自定义 ​

由于 Sail 本质上就是 Docker，几乎所有方面都可自由自定义。要发布 Sail 自带的 Dockerfile，可执行 sail:publish 命令：

shell
sail artisan sail:publish

运行该命令后，Laravel Sail 使用的 Dockerfile 及其他配置文件会放在应用根目录的 docker 目录中。自定义后，你可能希望更改 compose.yaml 中应用容器的镜像名称，然后用 build 命令重建容器。若在同一台机器上用 Sail 开发多个 Laravel 应用，为应用镜像指定唯一名称尤为重要：

shell
sail build --no-cache