Laravel Sail - Knowledge of Laravel

什么是 Sail

Laravel Sail 是一款轻量的命令行工具，用于操作 Laravel 的 Docker 开发环境。即便你不了解 Docker，也能搭建包含 PHP、MySQL、Redis 的 Laravel 应用。 Sail 的核心是位于项目根目录的 compose.yaml 文件和 sail 脚本。 sail 脚本提供了便捷的 CLI，用来操作 compose.yaml 中定义的 Docker 容器。 Laravel Sail 可运行在 macOS、Linux 以及 Windows（通过 WSL2）。

在 Laravel 13 中，Sail 不再是默认的开发环境。 项目脚手架 composer.json 已移除了 laravel/sail，取而代之的是 composer setup 命令。默认方案是在本地使用 PHP + SQLite。

composer setup
composer dev

如果需要 Docker 容器，仍然可以继续安装并使用 Sail。

Sail 是仅供本地开发使用的工具，不适用于生产环境。生产环境请另行准备合适的 Docker / 云平台方案。

安装

在已有项目中安装

使用 Composer 安装该包。

添加 Sail 包

composer require laravel/sail --dev

发布配置文件

执行 sail:install Artisan 命令。该命令会向项目根目录发布 compose.yaml，并在 .env 中添加必要的环境变量。

php artisan sail:install

你可以在交互式提示中选择要使用的服务，例如 MySQL、Redis、Mailpit 等。

启动 Sail

./vendor/bin/sail up

首次启动时会下载 Docker 镜像，需要一些时间。启动完成后可通过 http://localhost 访问应用。

如果使用的是 Docker Desktop for Linux，请执行 docker context use default 切换到 default 上下文。若容器内出现文件权限错误，请将 SUPERVISOR_PHP_USER 环境变量设置为 root。

添加额外服务

要向已有的 Sail 安装添加服务，使用 sail:add 命令。

php artisan sail:add

使用 Devcontainer

若希望在 Devcontainer 中开发，请使用 --devcontainer 选项。

php artisan sail:install --devcontainer

配置

设置 Shell 别名

默认情况下你需要每次输入 ./vendor/bin/sail。设置 shell 别名后就只需输入 sail 即可。

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

将其加入 ~/.zshrc 或 ~/.bashrc，然后重启 shell。

sail up

设置好别名后，本文中所有以 ./vendor/bin/sail 开头的命令都可以直接以 sail 代替。

重新构建镜像

若要让镜像内的包保持最新，可重新构建。

docker compose down -v

sail build --no-cache

sail up

启动与停止

要启动 compose.yaml 中定义的所有 Docker 容器，使用 up 命令。

# 前台启动
sail up

# 后台启动
sail up -d

停止时使用 stop 命令；若为前台启动，则可按 Ctrl + C。

sail stop

启动流程

运行命令

使用 Sail 时，应用运行在 Docker 容器内。 PHP、Artisan、Composer、Node / NPM 等命令都需要通过 sail 执行。

Laravel 官方文档中常见的 php artisan、composer、npm 命令，在 Sail 环境下需要在前面加上 sail。

PHP 命令

sail php --version

sail php script.php

Composer 命令

sail composer require laravel/sanctum

Artisan 命令

sail artisan migrate

sail artisan queue:work

Node / NPM 命令

sail node --version

sail npm run dev

# 使用 Yarn
sail yarn

容器 CLI（Shell）

也可以直接进入容器打开 Bash 会话。

sail shell

# 以 root 用户连接
sail root-shell

打开 Tinker 会话使用如下命令。

sail tinker

服务

以下是 Sail 提供的服务概览。可在安装时通过 sail:install 进行选择。

MySQL

默认包含在 compose.yaml 中。数据通过 Docker Volume 持久化。首次启动时会自动创建两个数据库：一个供应用使用，另一个是 testing。在 .env 中将 DB_HOST 设置为 mysql 即可让应用访问它。

DB_HOST=mysql
DB_PORT=3306

如需从本地机器连接，可使用 TablePlus 等 GUI 工具。默认端口为 3306。

Redis

在 .env 中将 REDIS_HOST 设置为 redis 即可访问 Redis。

REDIS_HOST=redis
REDIS_PORT=6379

Valkey

若使用 Valkey 作为 Redis 的替代，将 REDIS_HOST 设置为 valkey 即可。

Mailpit

用于捕获本地开发过程中的邮件发送，并在 Web UI 中预览。

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Sail 运行时，可以通过 http://localhost:8025 访问 Mailpit 的 Web UI。

Meilisearch / Typesense

可以与 Laravel Scout 集成，体验全文搜索。

Meilisearch: MEILISEARCH_HOST=http://meilisearch:7700
Typesense: TYPESENSE_HOST=typesense、TYPESENSE_PORT=8108 等

RustFS（S3 兼容存储）

若生产环境计划使用 Amazon S3，可以在本地模拟 S3 兼容存储。

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

运行测试

sail test

sail test --group orders

sail test 内部等同于 sail artisan test。默认会准备专用的 testing 数据库，不会影响开发数据。

Laravel Dusk

使用 Sail 时无需在本地安装 Selenium 就可运行 Dusk 浏览器测试。请取消 compose.yaml 中 Selenium 服务的注释。

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

在 Apple Silicon（M1/M2/M3）上请使用 selenium/standalone-chromium 镜像。

然后运行 Dusk 测试。

sail dusk

PHP / Node 版本

更改 PHP 版本

修改 compose.yaml 中 laravel.test 容器的 build.context。

# 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

更改后请重新构建镜像。

sail build --no-cache
sail up

追加 PHP 扩展

Sail 运行时镜像已包含常见 PHP 扩展。若应用需要额外扩展，可以在 compose.yaml 中 laravel.test 服务里通过 PHP_EXTENSIONS 构建参数以空格分隔来指定，在构建镜像时一并安装。

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'

更新 compose.yaml 之后请重新构建镜像。

sail build --no-cache
sail up

更改 Node 版本

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '20'

分享站点

为了让同事预览或测试 Webhook，你可以临时将站点暴露到外部。

sail share

会生成一个随机的 laravel-sail.site URL。为了让 URL 生成辅助函数正常工作，请在 bootstrap/app.php 中配置信任代理。

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

也可以指定子域名。

sail share --subdomain=my-sail-site

Xdebug

启用

先通过 sail:publish 发布配置文件，然后在 .env 中添加：

SAIL_XDEBUG_MODE=develop,debug,coverage

确认发布的 php.ini 文件包含以下配置：

[xdebug]
xdebug.mode=${XDEBUG_MODE}

修改后请重新构建镜像。

sail build --no-cache

CLI 调试

# 不使用 Xdebug 执行
sail artisan migrate

# 启用 Xdebug 执行
sail debug migrate

浏览器调试

在浏览器中启动调试会话的步骤请参阅 Xdebug 官方文档。若使用 PhpStorm，Zero-configuration debugging 的设置很方便。

Sail 使用 artisan serve 提供服务。只有 Laravel 8.53.0 及以后版本才接受 XDEBUG_CONFIG 与 XDEBUG_MODE。更早的版本下调试连接不会生效。

自定义

要自定义 Sail 的 Dockerfile 或配置文件，请使用 sail:publish 命令进行发布。

sail artisan sail:publish

发布后 Dockerfile 会放置在 docker/ 目录下。修改后请重新构建容器。

sail build --no-cache

与生产环境的区别

Sail 是仅用于本地开发的环境，不适合用于生产。生产环境的 Docker 部署可考虑 Laravel Cloud、Forge、Ploi 等服务，或者自行搭建 Docker Compose / Kubernetes 配置。

Sail 与生产环境的主要差异如下：

项目	Sail（本地）	生产环境
目的	开发与调试	提供服务
Xdebug	可启用	建议禁用
Mailpit	捕获邮件供预览	真实邮件服务器
数据持久化	Docker Volume	托管数据库等
性能	无优化	必须优化

​什么是 Sail

​安装

​在已有项目中安装

​添加额外服务

​使用 Devcontainer

​配置

​设置 Shell 别名

​重新构建镜像

​启动与停止

​启动流程

​运行命令

​PHP 命令

​Composer 命令

​Artisan 命令

​Node / NPM 命令

​容器 CLI（Shell）

​服务

​MySQL

​Redis

​Valkey

​Mailpit

​Meilisearch / Typesense

​RustFS（S3 兼容存储）

​运行测试

​Laravel Dusk

​PHP / Node 版本

​更改 PHP 版本

​追加 PHP 扩展

​更改 Node 版本

​分享站点

​Xdebug

​启用

​CLI 调试

​浏览器调试

​自定义

​与生产环境的区别

什么是 Sail

安装

在已有项目中安装

添加额外服务

使用 Devcontainer

配置

设置 Shell 别名

重新构建镜像

启动与停止

启动流程

运行命令

PHP 命令

Composer 命令

Artisan 命令

Node / NPM 命令

容器 CLI（Shell）

服务

MySQL

Redis

Valkey

Mailpit

Meilisearch / Typesense

RustFS（S3 兼容存储）

运行测试

Laravel Dusk

PHP / Node 版本

更改 PHP 版本

追加 PHP 扩展

更改 Node 版本

分享站点

Xdebug

启用

CLI 调试

浏览器调试

自定义

与生产环境的区别