Laravel Sail

• 簡介
• 安裝與設定
  • 重建 Sail 映像
  • 設定 Shell 別名
• 啟動與停止 Sail
• 執行指令
  • 執行 PHP 指令
  • 執行 Composer 指令
  • 執行 Artisan 指令
  • 執行 Node / NPM 指令
• 與資料庫互動
  • MySQL
  • MongoDB
  • Redis
  • Valkey
  • Meilisearch
  • Typesense
• 檔案儲存
• 執行測試
  • Laravel Dusk
• 預覽電子郵件
• 容器 CLI
• PHP 版本
  • 額外的 PHP 擴充功能
• Node 版本
• 分享您的網站
• 使用 Xdebug 除錯
  • Xdebug CLI 使用方式
  • Xdebug 瀏覽器使用方式
• 自訂

簡介

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

安裝與設定

您可以使用 Composer 套件管理器安裝 Sail：

composer require laravel/sail --dev

Sail 安裝完成後，您可以執行 sail:install Artisan 指令。此指令將發佈 Sail 的 compose.yaml 檔案到您應用程式的根目錄，並使用連接 Docker 服務所需的環境變數來修改您的 .env 檔案：

php artisan sail:install

最後，您可以啟動 Sail。要繼續學習如何使用 Sail，請繼續閱讀本文件的其餘部分：

./vendor/bin/sail up

[!WARNING] 如果您使用的是 Docker Desktop for Linux，您應該使用 default Docker 上下文，方法是執行以下指令：docker context use default。此外，如果您在容器內遇到檔案權限錯誤，您可能需要將 SUPERVISOR_PHP_USER 環境變數設為 root。

新增額外服務

如果您想要在現有的 Sail 安裝中新增額外的服務，您可以執行 sail:add Artisan 指令：

php artisan sail:add

使用 Devcontainers

如果您想要在 Devcontainer 中開發，您可以向 sail:install 指令提供 --devcontainer 選項。--devcontainer 選項將指示 sail:install 指令發佈一個預設的 .devcontainer/devcontainer.json 檔案到您應用程式的根目錄：

php artisan sail:install --devcontainer

重建 Sail 映像

有時您可能想要完全重建您的 Sail 映像，以確保所有映像的套件和軟體都是最新的。您可以使用 build 指令來實現：

docker compose down -v

sail build --no-cache

sail up

設定 Shell 別名

預設情況下，Sail 指令是使用所有新 Laravel 應用程式中包含的 vendor/bin/sail 腳本來呼叫的：

./vendor/bin/sail up

然而，與其反覆輸入 vendor/bin/sail 來執行 Sail 指令，您可能希望設定一個 shell 別名，讓您可以更輕鬆地執行 Sail 的指令：

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

為了確保此別名始終可用，您可以將其新增到您主目錄中的 shell 設定檔，例如 ~/.zshrc 或 ~/.bashrc，然後重新啟動您的 shell。

shell 別名設定完成後，您只需輸入 sail 即可執行 Sail 指令。本文件其餘部分的範例將假設您已設定此別名：

sail up

啟動與停止 Sail

Laravel Sail 的 compose.yaml 檔案定義了多種协同工作的 Docker 容器來幫助您建構 Laravel 應用程式。每個容器都是 compose.yaml 檔案的 services 設定中的一個條目。laravel.test 容器是將為您的應用程式提供服務的主要應用程式容器。

在啟動 Sail 之前，您應該確保本地電腦上沒有其他 Web 伺服器或資料庫正在運行。要啟動應用程式 compose.yaml 檔案中定義的所有 Docker 容器，您應該執行 up 指令：

sail up

要在背景啟動所有 Docker 容器，您可以在「分離」模式下啟動 Sail：

sail up -d

應用程式容器啟動後，您可以在瀏覽器中透過以下網址存取專案：http://localhost。

要停止所有容器，您只需按 Control + C 來停止容器的執行。或者，如果容器正在背景運行，您可以使用 stop 指令：

sail stop

執行指令

使用 Laravel Sail 時，您的應用程式是在 Docker 容器中執行的，與您的本地電腦隔離。然而，Sail 提供了一種便利的方式來對您的應用程式執行各種指令，例如任意 PHP 指令、Artisan 指令、Composer 指令和 Node / NPM 指令。

閱讀 Laravel 文件時，您經常會看到對 Composer、Artisan 和 Node / NPM 指令的引用，但這些指令並未引用 Sail。這些範例假設這些工具已安裝在您的本地電腦上。如果您使用 Sail 作為本地 Laravel 開發環境，您應該使用 Sail 來執行這些指令：

# 在本地執行 Artisan 指令...
php artisan queue:work

# 在 Laravel Sail 中執行 Artisan 指令...
sail artisan queue:work

執行 PHP 指令

可以使用 php 指令來執行 PHP 指令。當然，這些指令將使用為您的應用程式設定的 PHP 版本來執行。要了解更多關於 Laravel Sail 可用的 PHP 版本，請參閱 PHP 版本文件：

sail php --version

sail php script.php

執行 Composer 指令

可以使用 composer 指令來執行 Composer 指令。Laravel Sail 的應用程式容器包含一個 Composer 安裝：

sail composer require laravel/sanctum

執行 Artisan 指令

可以使用 artisan 指令來執行 Laravel Artisan 指令：

sail artisan queue:work

執行 Node / NPM 指令

可以使用 node 指令來執行 Node 指令，而 NPM 指令可以使用 npm 指令來執行：

sail node --version

sail npm run dev

如果您願意，可以使用 Yarn 代替 NPM：

sail yarn

與資料庫互動

MySQL

您可能已經注意到，應用程式的 compose.yaml 檔案中包含一個 MySQL 容器的條目。此容器使用 Docker 卷，這樣即使停止和重新啟動容器，儲存在資料庫中的資料也會被持久化。

此外，MySQL 容器首次啟動時，它會為您建立兩個資料庫。第一個資料庫使用您的 DB_DATABASE 環境變數的值命名，用於您的本地開發。第二個是一個名為 testing 的專用測試資料庫，它將確保您的測試不會干擾您的開發資料。

啟動容器後，您可以透過在應用程式的 .env 檔案中將 DB_HOST 環境變數設為 mysql 來連接到應用程式中的 MySQL 實例。

要從您的本地機器連接到應用程式的 MySQL 資料庫，您可以使用圖形化資料庫管理應用程式，例如 TablePlus。預設情況下，MySQL 資料庫在 localhost 的連接埠 3306 上可存取，存取憑證對應於您的 DB_USERNAME 和 DB_PASSWORD 環境變數的值。或者，您可以以 root 使用者身分連接，它也使用您的 DB_PASSWORD 環境變數的值作為其密碼。

MongoDB

如果您在安裝 Sail 時選擇安裝 MongoDB 服務，應用程式的 compose.yaml 檔案中將包含一個 MongoDB Atlas Local 容器的條目，該容器提供具有 Atlas 功能（如搜尋索引）的 MongoDB 文件資料庫。此容器使用 Docker 卷，這樣即使停止和重新啟動容器，儲存在資料庫中的資料也會被持久化。

啟動容器後，您可以透過在應用程式的 .env 檔案中將 MONGODB_URI 環境變數設為 mongodb://mongodb:27017 來連接到應用程式中的 MongoDB 實例。預設情況下會停用認證，但您可以在啟動 mongodb 容器之前設定 MONGODB_USERNAME 和 MONGODB_PASSWORD 環境變數來啟用認證。然後，將憑證新增到連接字串：

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

為了與您的應用程式無縫整合 MongoDB，您可以安裝 MongoDB 維護的官方套件。

要從您的本地機器連接到應用程式的 MongoDB 資料庫，您可以使用圖形化介面，例如 Compass。預設情況下，MongoDB 資料庫在 localhost 的連接埠 27017 上可存取。

Redis

應用程式的 compose.yaml 檔案中還包含一個 Redis 容器的條目。此容器使用 Docker 卷，這樣即使停止和重新啟動容器，儲存在 Redis 實例中的資料也會被持久化。啟動容器後，您可以透過在應用程式的 .env 檔案中將 REDIS_HOST 環境變數設為 redis 來連接到應用程式中的 Redis 實例。

要從您的本地機器連接到應用程式的 Redis 資料庫，您可以使用圖形化資料庫管理應用程式，例如 TablePlus。預設情況下，Redis 資料庫在 localhost 的連接埠 6379 上可存取。

Valkey

如果您在安裝 Sail 時選擇安裝 Valkey 服務，應用程式的 compose.yaml 檔案中將包含一個 Valkey 的條目。此容器使用 Docker 卷，這樣即使停止和重新啟動容器，儲存在 Valkey 實例中的資料也會被持久化。您可以透過在應用程式的 .env 檔案中將 REDIS_HOST 環境變數設為 valkey 來連接到此容器。

要從您的本地機器連接到應用程式的 Valkey 資料庫，您可以使用圖形化資料庫管理應用程式，例如 TablePlus。預設情況下，Valkey 資料庫在 localhost 的連接埠 6379 上可存取。

Meilisearch

如果您在安裝 Sail 時選擇安裝 Meilisearch 服務，應用程式的 compose.yaml 檔案中將包含一個與 Laravel Scout 整合的強大搜尋引擎的條目。啟動容器後，您可以透過將 MEILISEARCH_HOST 環境變數設為 http://meilisearch:7700 來連接到應用程式中的 Meilisearch 實例。

從您的本地機器，您可以透過在瀏覽器中導航到 http://localhost:7700 來存取 Meilisearch 的網頁管理面板。

Typesense

如果您在安裝 Sail 時選擇安裝 Typesense 服務，應用程式的 compose.yaml 檔案中將包含一個與 Laravel Scout 原生整合的閃電般快速的開源搜尋引擎的條目。啟動容器後，您可以透過設定以下環境變數來連接到應用程式中的 Typesense 實例：

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，RustFS 設定部分將被新增到您應用程式的 compose.yaml 檔案中。

預設情況下，應用程式的 filesystems 設定檔已經包含一個 s3 磁碟的磁碟設定。除了使用此磁碟與 Amazon S3 互動外，您還可以透過簡單地修改控制其設定的相關環境變數來使用它與任何 S3 相容的檔案儲存服務（如 RustFS）互動。例如，使用 RustFS 時，您的檔案系統環境變數設定應定義如下：

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 指令：

sail test

sail test --group orders

Sail test 指令等於執行 test Artisan 指令：

sail artisan test

預設情況下，Sail 將建立一個專用的 testing 資料庫，這樣您的測試就不會干擾資料庫的當前狀態。在預設的 Laravel 安裝中，Sail 還會設定您的 phpunit.xml 檔案在執行測試時使用此資料庫：

<env name="DB_DATABASE" value="testing"/>

Laravel Dusk

Laravel Dusk 提供了一個表達力強、易於使用的瀏覽器自動化和測試 API。多虧了 Sail，您可以在無需在本地電腦上安裝 Selenium 或其他工具的情況下運行這些測試。要開始，請取消註解應用程式 compose.yaml 檔案中的 Selenium 服務：

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 條目：

depends_on:
    - mysql
    - redis
    - selenium

最後，您可以啟動 Sail 並執行 dusk 指令來運行您的 Dusk 測試套件：

sail dusk

Apple Silicon 上的 Selenium

如果您的本地機器包含 Apple Silicon 晶片，您的 selenium 服務必須使用 selenium/standalone-chromium 映像：

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 會攔截在本地開發期間由您的應用程式發送的電子郵件，並提供一個便利的網頁介面，讓您可以在瀏覽器中預覽您的電子郵件訊息。使用 Sail 時，Mailpit 的預設主機是 mailpit，可透過連接埠 1025 存取：

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Sail 運行時，您可以透過以下網址存取 Mailpit 網頁介面：http://localhost:8025

容器 CLI

有時您可能想要在應用程式的容器中開始一個 Bash 會話。您可以使用 shell 指令連接到應用程式的容器，允許您檢查其檔案和已安裝的服務，以及在容器內執行任意 shell 指令：

sail shell

sail root-shell

要開始一個新的 Laravel Tinker 會話，您可以執行 tinker 指令：

sail tinker

PHP 版本

Sail 目前支援透過 PHP 8.5、8.4、8.3、8.2、8.1 或 PHP 8.0 為您的應用程式提供服務。Sail 使用的預設 PHP 版本目前是 PHP 8.5。要變更用於為您的應用程式提供服務的 PHP 版本，您應該更新應用程式 compose.yaml 檔案中 laravel.test 容器的 build 定義：

# 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 檔案中：

image: sail-8.2/app

更新應用程式的 compose.yaml 檔案後，您應該重建您的容器映像：

sail build --no-cache

sail up

額外的 PHP 擴充功能

Sail 的運行時映像包含一組常見的 PHP 擴充功能。如果您的應用程式需要額外的擴充功能，您可以在建構映像時透過在應用程式 compose.yaml 檔案的 laravel.test 服務中新增以空格分隔的 PHP_EXTENSIONS build 參數來安裝它們：

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

更新應用程式的 compose.yaml 檔案後，您應該重建您的容器映像。

Node 版本

Sail 預設安裝 Node 24。要變更建構映像時安裝的 Node 版本，您可以更新應用程式 compose.yaml 檔案中 laravel.test 服務的 build.args 定義：

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

更新應用程式的 compose.yaml 檔案後，您應該重建您的容器映像：

sail build --no-cache

sail up

分享您的網站

有時您可能需要公開分享您的網站，以便與同事預覽您的網站或測試與應用程式的 webhook 整合。要分享您的網站，您可以使用 share 指令。執行此指令後，您將獲得一個隨機的 laravel-sail.site URL，您可以用它來存取您的應用程式：

sail share

透過 share 指令分享您的網站時，您應該在應用程式的 bootstrap/app.php 檔案中使用 trustProxies 中介層方法來設定應用程式的可信代理。否則，URL 生成輔助函數（如 url 和 route）將無法確定在 URL 生成期間應使用正確的 HTTP 主機：

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

如果您想要選擇共享網站的子網域，您可以在執行 share 指令時提供 subdomain 選項：

sail share --subdomain=my-sail-site

[!NOTE] share 指令由 Expose 提供支援，這是 BeyondCode 的一個開源隧道服務。

使用 Xdebug 除錯

Laravel Sail 的 Docker 設定包含對 Xdebug 的支援，這是一個流行且功能強大的 PHP 除錯器。要啟用 Xdebug，請確保您已發佈您的 Sail 設定。然後，將以下變數新增到您應用程式的 .env 檔案中以設定 Xdebug：

SAIL_XDEBUG_MODE=develop,debug,coverage

接下來，確保您已發佈的 php.ini 檔案包含以下設定，以便 Xdebug 在指定的模式下啟用：

[xdebug]
xdebug.mode=${XDEBUG_MODE}

修改 php.ini 檔案後，請記得重建您的 Docker 映像，以便您對 php.ini 檔案的變更生效：

sail build --no-cache

Linux 主機 IP 設定

在內部，XDEBUG_CONFIG 環境變數被定義為 client_host=host.docker.internal，這樣 Xdebug 將為 Mac 和 Windows (WSL2) 正確設定。如果您的本地機器運行 Linux 且您使用的是 Docker 20.10+，host.docker.internal 可用，無需手動設定。

對於低於 20.10 的 Docker 版本，Linux 不支援 host.docker.internal，您需要手動定義主機 IP。為此，請透過在 compose.yaml 檔案中定義自訂網路來為容器設定靜態 IP：

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 變數：

SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Xdebug CLI 使用方式

sail debug 指令可用於在執行 Artisan 指令時開始除錯會話：

# 不使用 Xdebug 執行 Artisan 指令...
sail artisan migrate

# 使用 Xdebug 執行 Artisan 指令...
sail debug migrate

Xdebug 瀏覽器使用方式

要透過瀏覽器與應用程式互動時除錯應用程式，請按照 Xdebug 提供的說明從瀏覽器啟動 Xdebug 會話。

如果您使用的是 PhpStorm，請查閱 JetBrains 關於零設定除錯的文件。

[!WARNING] Laravel Sail 依賴 artisan serve 來為您的應用程式提供服務。artisan serve 指令自 Laravel 8.53.0 版本起僅接受 XDEBUG_CONFIG 和 XDEBUG_MODE 變數。較舊版本的 Laravel（8.52.0 及以下）不支援這些變數，且不會接受除錯連接。

自訂

由於 Sail 就是 Docker，您可以自由地自訂幾乎所有關於它的內容。要發佈 Sail 自己的 Dockerfile，您可以執行 sail:publish 指令：

sail artisan sail:publish

執行此指令後，Laravel Sail 使用的 Dockerfile 和其他設定檔將被放置在您應用程式根目錄的 docker 目錄中。自訂 Sail 安裝後，您可能希望變更應用程式 compose.yaml 檔案中應用程式容器的映像名稱。完成後，使用 build 指令重建您的應用程式容器。如果您使用 Sail 在單台機器上開發多個 Laravel 應用程式，為應用程式映像分配一個唯一名稱尤其重要：

sail build --no-cache