> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Sail

> 介绍如何使用 Laravel Sail 零配置搭建基于 Docker 的本地开发环境。

## 什么是 Sail

[Laravel Sail](https://github.com/laravel/sail) 是一款轻量的命令行工具，用于操作 Laravel 的 Docker 开发环境。
即便你不了解 Docker，也能搭建包含 PHP、MySQL、Redis 的 Laravel 应用。

Sail 的核心是位于项目根目录的 `compose.yaml` 文件和 `sail` 脚本。
`sail` 脚本提供了便捷的 CLI，用来操作 `compose.yaml` 中定义的 Docker 容器。

Laravel Sail 可运行在 macOS、Linux 以及 Windows（通过 [WSL2](https://docs.microsoft.com/en-us/windows/wsl/about)）。

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

  ```shell theme={null}
  composer setup
  composer dev
  ```

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

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

***

## 安装

### 在已有项目中安装

使用 Composer 安装该包。

<Steps>
  <Step title="添加 Sail 包">
    ```shell theme={null}
    composer require laravel/sail --dev
    ```
  </Step>

  <Step title="发布配置文件">
    执行 `sail:install` Artisan 命令。
    该命令会向项目根目录发布 `compose.yaml`，并在 `.env` 中添加必要的环境变量。

    ```shell theme={null}
    php artisan sail:install
    ```

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

  <Step title="启动 Sail">
    ```shell theme={null}
    ./vendor/bin/sail up
    ```

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

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

### 添加额外服务

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

```shell theme={null}
php artisan sail:add
```

### 使用 Devcontainer

若希望在 [Devcontainer](https://code.visualstudio.com/docs/remote/containers) 中开发，请使用 `--devcontainer` 选项。

```shell theme={null}
php artisan sail:install --devcontainer
```

***

## 配置

### 设置 Shell 别名

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

```shell theme={null}
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'
```

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

```shell theme={null}
sail up
```

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

### 重新构建镜像

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

```shell theme={null}
docker compose down -v

sail build --no-cache

sail up
```

***

## 启动与停止

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

```shell theme={null}
# 前台启动
sail up

# 后台启动
sail up -d
```

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

```shell theme={null}
sail stop
```

### 启动流程

```mermaid theme={null}
flowchart TD
    A["执行 sail up"] --> B{"Docker 镜像<br>是否存在？"}
    B -- 否 --> C["构建/下载镜像"]
    C --> D["启动容器"]
    B -- 是 --> D
    D --> E["laravel.test 容器<br>（应用）启动"]
    D --> F["mysql 容器启动"]
    D --> G["redis 容器启动"]
    D --> H["mailpit 容器启动"]
    E --> I["可通过 http://localhost 访问"]
```

***

## 运行命令

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

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

### PHP 命令

```shell theme={null}
sail php --version

sail php script.php
```

### Composer 命令

```shell theme={null}
sail composer require laravel/sanctum
```

### Artisan 命令

```shell theme={null}
sail artisan migrate

sail artisan queue:work
```

### Node / NPM 命令

```shell theme={null}
sail node --version

sail npm run dev

# 使用 Yarn
sail yarn
```

### 容器 CLI（Shell）

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

```shell theme={null}
sail shell

# 以 root 用户连接
sail root-shell
```

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

```shell theme={null}
sail tinker
```

***

## 服务

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

### MySQL

默认包含在 `compose.yaml` 中。
数据通过 Docker Volume 持久化。首次启动时会自动创建两个数据库：一个供应用使用，另一个是 `testing`。

在 `.env` 中将 `DB_HOST` 设置为 `mysql` 即可让应用访问它。

```ini theme={null}
DB_HOST=mysql
DB_PORT=3306
```

如需从本地机器连接，可使用 [TablePlus](https://tableplus.com) 等 GUI 工具。默认端口为 `3306`。

### Redis

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

```ini theme={null}
REDIS_HOST=redis
REDIS_PORT=6379
```

### Valkey

若使用 [Valkey](https://valkey.io/) 作为 Redis 的替代，将 `REDIS_HOST` 设置为 `valkey` 即可。

### Mailpit

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

```ini theme={null}
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null
```

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

### Meilisearch / Typesense

可以与 [Laravel Scout](/zh/scout) 集成，体验全文搜索。

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

### RustFS（S3 兼容存储）

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

```ini theme={null}
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
```

***

## 运行测试

```shell theme={null}
sail test

sail test --group orders
```

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

### Laravel Dusk

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

```yaml theme={null}
selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail
```

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

然后运行 Dusk 测试。

```shell theme={null}
sail dusk
```

***

## PHP / Node 版本

### 更改 PHP 版本

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

```yaml theme={null}
# 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
```

更改后请重新构建镜像。

```shell theme={null}
sail build --no-cache
sail up
```

### 追加 PHP 扩展

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

```yaml theme={null}
build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'
```

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

```shell theme={null}
sail build --no-cache
sail up
```

### 更改 Node 版本

```yaml theme={null}
build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '20'
```

***

## 分享站点

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

```shell theme={null}
sail share
```

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

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

也可以指定子域名。

```shell theme={null}
sail share --subdomain=my-sail-site
```

***

## Xdebug

### 启用

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

```ini theme={null}
SAIL_XDEBUG_MODE=develop,debug,coverage
```

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

```ini theme={null}
[xdebug]
xdebug.mode=${XDEBUG_MODE}
```

修改后请重新构建镜像。

```shell theme={null}
sail build --no-cache
```

### CLI 调试

```shell theme={null}
# 不使用 Xdebug 执行
sail artisan migrate

# 启用 Xdebug 执行
sail debug migrate
```

### 浏览器调试

在浏览器中启动调试会话的步骤请参阅 [Xdebug 官方文档](https://xdebug.org/docs/step_debug#web-application)。
若使用 PhpStorm，[Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) 的设置很方便。

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

***

## 自定义

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

```shell theme={null}
sail artisan sail:publish
```

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

```shell theme={null}
sail build --no-cache
```

***

## 与生产环境的区别

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

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

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


## Related topics

- [Laravel Boost Custom Agent for GitHub Copilot CLI](/zh/packages/laravel-boost-copilot-cli.md)
- [Laravel Scout](/zh/scout.md)
- [Artisan 控制台](/zh/artisan.md)
- [Redis](/zh/redis.md)
- [开始学习 Laravel 前需要具备的知识](/zh/true-tutorial.md)