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

使用 Docker Desktop for Linux 時，執行 docker context use default 以使用 default context。若容器內出現檔案權限錯誤，請將 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

設定別名之後，本文所有指令範例中可以用 sail 取代 ./vendor/bin/sail。

重新建置 image

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

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 session。

sail shell

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

要開啟 Tinker session：

sail tinker

服務

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

MySQL

預設已包含在 compose.yaml 中。資料以 Docker Volume 永久保存。首次啟動時會自動建立應用用與 testing 用共 2 個資料庫。將 .env 的 DB_HOST 設為 mysql，即可從應用存取。

DB_HOST=mysql
DB_PORT=3306

要從本機連線，可使用 TablePlus 等 GUI 工具。預設 port 為 3306。

Redis

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

REDIS_HOST=redis
REDIS_PORT=6379

Valkey

若要使用 Redis 的替代方案 Valkey，將 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 image。

之後執行 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

變更後請重新建置 image。

sail build --no-cache
sail up

追加 PHP 擴充功能

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

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

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

sail build --no-cache
sail up

變更 Node 版本

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

對外分享網站

為了讓同事預覽或測試 Webhook，可以將網站暫時對外公開。

sail share

會發放隨機的 laravel-sail.site URL。為了讓 URL 產生 helper 正確運作，請在 bootstrap/app.php 設定可信任的 proxy。

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

變更後重新建置 image：

sail build --no-cache

CLI 除錯

# 不使用 Xdebug 執行
sail artisan migrate

# 使用 Xdebug 執行
sail debug migrate

瀏覽器除錯

從瀏覽器啟動除錯 session 的步驟，請參考 Xdebug 官方文件。若使用 PhpStorm，設定 Zero-configuration debugging 會很方便。

Sail 使用 artisan serve 提供應用程式。支援 XDEBUG_CONFIG 與 XDEBUG_MODE 的是 Laravel 8.53.0 以後版本。更舊的版本除錯連線無法運作。

自訂

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

sail artisan sail:publish

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

sail build --no-cache

與正式環境的差異

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

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

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

​什麼是 Sail

​安裝

​於既有專案安裝

​追加服務

​使用 Devcontainer

​設定

​Shell 別名設定

​重新建置 image

​啟動與停止

​啟動流程

​執行指令

​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 別名設定

重新建置 image

啟動與停止

啟動流程

執行指令

PHP 指令

Composer 指令

Artisan 指令

Node / NPM 指令

容器 CLI（shell）

服務

MySQL

Redis

Valkey

Mailpit

Meilisearch / Typesense

RustFS（S3 相容儲存）

執行測試

Laravel Dusk

PHP／Node 版本

變更 PHP 版本

追加 PHP 擴充功能

變更 Node 版本

對外分享網站

Xdebug

啟用

CLI 除錯

瀏覽器除錯

自訂

與正式環境的差異