> ## 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 image 下載會較耗時。
    啟動後可從 `http://localhost` 存取應用程式。
  </Step>
</Steps>

<Warning>
  使用 Docker Desktop for Linux 時，執行 `docker context use default` 以使用 `default` context。
  若容器內出現檔案權限錯誤，請將 `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>
  設定別名之後，本文所有指令範例中可以用 `sail` 取代 `./vendor/bin/sail`。
</Tip>

### 重新建置 image

若想保持套件為最新狀態，可重新建置 image。

```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 image<br>是否存在？"}
    B -- 否 --> C["建置／下載<br>image"]
    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 session。

```shell theme={null}
sail shell

# 以 root 使用者連線
sail root-shell
```

要開啟 Tinker session：

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

***

## 服務

以下為 Sail 提供的服務概要。安裝時可透過 `sail:install` 選擇。

### MySQL

預設已包含在 `compose.yaml` 中。
資料以 Docker Volume 永久保存。首次啟動時會自動建立應用用與 `testing` 用共 2 個資料庫。

將 `.env` 的 `DB_HOST` 設為 `mysql`，即可從應用存取。

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

要從本機連線，可使用 [TablePlus](https://tableplus.com) 等 GUI 工具。預設 port 為 `3306`。

### Redis

將 `.env` 的 `REDIS_HOST` 設為 `redis`，即可從應用存取 Redis。

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

### Valkey

若要使用 Redis 的替代方案 [Valkey](https://valkey.io/)，將 `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-TW/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` image。
</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
```

變更後請重新建置 image。

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

### 追加 PHP 擴充功能

Sail 的 runtime image 已包含常用的 PHP 擴充功能。若應用程式需要額外擴充功能，可於 `compose.yaml` 的 `laravel.test` 服務加入以空白分隔的 `PHP_EXTENSIONS` build 引數，在建置 image 時安裝。

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

更新 `compose.yaml` 後請重新建置容器 image。

```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 產生 helper 正確運作，請在 `bootstrap/app.php` 設定可信任的 proxy。

```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}
```

變更後重新建置 image：

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

### CLI 除錯

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

# 使用 Xdebug 執行
sail debug migrate
```

### 瀏覽器除錯

從瀏覽器啟動除錯 session 的步驟，請參考 [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` 提供應用程式。
  支援 `XDEBUG_CONFIG` 與 `XDEBUG_MODE` 的是 Laravel 8.53.0 以後版本。
  更舊的版本除錯連線無法運作。
</Warning>

***

## 自訂

要自訂 Sail 的 Dockerfile 或設定檔，使用 `sail:publish` 指令發布。

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

發布後 `docker/` 目錄中會放置 Dockerfile。
變更後請重新建置容器。

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

***

## 與正式環境的差異

<Warning>
  Sail 是本機開發專用環境。並非設計用於正式環境。
  正式環境的 Docker 部署，可考慮 Laravel Cloud、Forge、Ploi 等服務，
  或自訂的 Docker Compose／Kubernetes 配置。
</Warning>

Sail 與正式環境的主要差異整理如下：

| 項目      | Sail（本機）      | 正式環境    |
| ------- | ------------- | ------- |
| 目的      | 開發、除錯         | 提供服務    |
| Xdebug  | 可啟用           | 建議停用    |
| Mailpit | 攔截郵件並預覽       | 實際郵件伺服器 |
| 資料持久化   | Docker Volume | 託管 DB 等 |
| 效能      | 未最佳化          | 必須最佳化   |


## Related topics

- [Laravel Boost Custom Agent for GitHub Copilot CLI](/zh-TW/packages/laravel-boost-copilot-cli.md)
- [Laravel Scout](/zh-TW/scout.md)
- [Artisan Console](/zh-TW/artisan.md)
- [Redis](/zh-TW/redis.md)
- [開始學習 Laravel 前需要具備的知識](/zh-TW/true-tutorial.md)