跳到內容
Laravel

Laravel Sail

簡介

Laravel Sail 是一個輕量級的命令列介面，用於與 Laravel 的預設 Docker 開發環境互動。Sail 為使用 PHP、MySQL 和 Redis 建構 Laravel 應用程式提供了一個很好的起點，而無需事先具備 Docker 經驗。

從本質上講，Sail 是 docker-compose.yml 檔案和儲存在專案根目錄中的 sail 腳本。sail 腳本提供了一個 CLI，其中包含用於與 docker-compose.yml 檔案定義的 Docker 容器互動的便捷方法。

macOS、Linux 和 Windows（透過 WSL2）支援 Laravel Sail。

安裝與設定

Laravel Sail 會自動安裝到所有新的 Laravel 應用程式中，因此您可以立即開始使用它。要了解如何建立新的 Laravel 應用程式，請查閱 Laravel 的 安裝文件，以了解您的作業系統。在安裝期間，系統會要求您選擇您的應用程式將與哪些 Sail 支援的服務互動。

將 Sail 安裝到現有的應用程式

如果您有興趣將 Sail 與現有的 Laravel 應用程式一起使用，您可以簡單地使用 Composer 套件管理器安裝 Sail。當然，這些步驟假設您現有的本機開發環境允許您安裝 Composer 相依性

composer require laravel/sail --dev

安裝 Sail 後，您可以執行 sail:install Artisan 命令。此命令會將 Sail 的 docker-compose.yml 檔案發佈到您的應用程式的根目錄，並使用必要的環境變數修改您的 .env 檔案，以便連線到 Docker 服務

php artisan sail:install

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

./vendor/bin/sail up
exclamation

如果您使用 Docker Desktop for Linux，您應該執行以下命令來使用 default Docker 上下文：docker context use default。

新增其他服務

如果您想將其他服務新增至現有的 Sail 安裝，您可以執行 sail:add Artisan 命令

php artisan sail:add

使用 Devcontainers

如果您想在 Devcontainer 中開發，您可以將 --devcontainer 選項提供給 sail:install 命令。--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

但是，您可能希望設定一個 shell 別名，讓您可以更輕鬆地執行 Sail 的命令，而不是重複輸入 vendor/bin/sail 來執行 Sail 命令

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

為了確保此功能始終可用，您可以將其新增至您主目錄中的 shell 組態檔案，例如 ~/.zshrc 或 ~/.bashrc，然後重新啟動您的 shell。

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

sail up

啟動與停止 Sail

Laravel Sail 的 docker-compose.yml 檔案定義了各種 Docker 容器，這些容器協同工作以幫助您建構 Laravel 應用程式。這些容器中的每一個都是您 docker-compose.yml 檔案的 services 組態中的一個項目。laravel.test 容器是主要應用程式容器，它將為您的應用程式提供服務。

在啟動 Sail 之前，您應確保您的本機電腦上沒有其他網頁伺服器或資料庫正在執行。若要啟動應用程式的 docker-compose.yml 檔案中定義的所有 Docker 容器，您應執行 up 命令

sail up

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

sail up -d

啟動應用程式的容器後，您可以在您的網頁瀏覽器中透過 https://127.0.0.1 存取該專案。

若要停止所有容器，您只需按下 Control + C 即可停止容器的執行。或者，如果容器在背景中執行，您可以使用 stop 命令

sail stop

執行命令

當使用 Laravel Sail 時，您的應用程式會在 Docker 容器中執行，並且與您的本機電腦隔離。但是，Sail 提供了一個方便的方式來對您的應用程式執行各種命令，例如任意 PHP 命令、Artisan 命令、Composer 命令和 Node / NPM 命令。

在閱讀 Laravel 文件時，您經常會看到對 Composer、Artisan 和 Node / NPM 命令的參考，這些命令沒有參考 Sail。 這些範例假設這些工具已安裝在您的本機電腦上。如果您使用 Sail 作為您的本機 Laravel 開發環境，您應該使用 Sail 執行這些命令

# Running Artisan commands locally...
php artisan queue:work
 
# Running Artisan commands within Laravel Sail...
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

為現有的應用程式安裝 Composer 相依性

如果您正在與團隊開發應用程式，您可能不是最初建立 Laravel 應用程式的人。因此，在您將應用程式的存放庫複製到本機電腦後，不會安裝應用程式的任何 Composer 相依性，包括 Sail。

您可以透過導覽至應用程式的目錄並執行下列命令來安裝應用程式的相依性。此命令會使用一個小型 Docker 容器，其中包含 PHP 和 Composer 來安裝應用程式的相依性

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php84-composer:latest \
    composer install --ignore-platform-reqs

當使用 laravelsail/phpXX-composer 映像檔時，您應使用您計劃用於應用程式的相同 PHP 版本 (80、81、82、83 或 84)。

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

您可能已經注意到，您的應用程式的 docker-compose.yml 檔案包含一個 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 服務，您應用程式的 docker-compose.yml 檔案將包含一個 MongoDB Atlas Local 容器的條目，該容器提供 MongoDB 文件資料庫，並具備 Atlas 的功能，如 搜尋索引。這個容器使用 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

您應用程式的 docker-compose.yml 檔案也包含一個 Redis 容器的條目。這個容器使用 Docker 卷宗，以便即使停止並重新啟動容器，Redis 資料中儲存的資料也能夠持久保存。一旦您啟動了容器，您可以透過在應用程式的 .env 檔案中將 REDIS_HOST 環境變數設定為 redis，來連線到應用程式內的 Redis 執行個體。

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

Meilisearch

如果您在安裝 Sail 時選擇安裝 Meilisearch 服務，您應用程式的 docker-compose.yml 檔案將包含這個強大的搜尋引擎的條目，該引擎已與 Laravel Scout 整合。一旦您啟動了容器，您可以透過將 MEILISEARCH_HOST 環境變數設定為 http://meilisearch:7700，來連線到應用程式內的 Meilisearch 執行個體。

從您的本機，您可以透過在網頁瀏覽器中導覽至 https://127.0.0.1:7700 來存取 Meilisearch 的網頁管理面板。

Typesense

如果您在安裝 Sail 時選擇安裝 Typesense 服務，您應用程式的 docker-compose.yml 檔案將包含這個極速的開放原始碼搜尋引擎的條目，該引擎已原生與 Laravel Scout 整合。一旦您啟動了容器，您可以透過設定以下環境變數來連線到應用程式內的 Typesense 執行個體

TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz

從您的本機，您可以透過 https://127.0.0.1:8108 存取 Typesense 的 API。

檔案儲存

如果您計劃在生產環境中執行應用程式時使用 Amazon S3 儲存檔案，您可能希望在安裝 Sail 時安裝 MinIO 服務。MinIO 提供與 S3 相容的 API，您可以使用 Laravel 的 s3 檔案儲存驅動程式在本地開發，而無需在生產 S3 環境中建立「測試」儲存儲存區。如果您選擇在安裝 Sail 時安裝 MinIO，則會將 MinIO 設定區段新增至您應用程式的 docker-compose.yml 檔案。

預設情況下，您應用程式的 filesystems 組態檔案已經包含 s3 磁碟的磁碟組態。除了使用此磁碟與 Amazon S3 互動之外，您還可以透過修改控制其組態的相關環境變數，使用它與任何與 S3 相容的檔案儲存服務 (例如 MinIO) 互動。例如，當使用 MinIO 時，您的檔案系統環境變數組態應定義如下

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://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

為了讓 Laravel 的 Flysystem 整合在使用 MinIO 時產生正確的 URL，您應該定義 AWS_URL 環境變數，使其符合您應用程式的本機 URL，並在 URL 路徑中包含儲存區名稱

AWS_URL=https://127.0.0.1:9000/local

您可以透過 MinIO 主控台建立儲存區，該主控台可於 https://127.0.0.1:8900 存取。MinIO 主控台的預設使用者名稱為 sail，而預設密碼為 password。

exclamation

當使用 MinIO 時，不支援透過 temporaryUrl 方法產生臨時儲存 URL。

執行測試

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 或其他工具。首先，取消註解您應用程式 docker-compose.yml 檔案中的 Selenium 服務

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

接下來，請確保您應用程式 docker-compose.yml 檔案中的 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 的預設 docker-compose.yml 檔案包含 Mailpit 的服務條目。Mailpit 會攔截您的應用程式在本機開發期間傳送的電子郵件，並提供方便的網頁介面，讓您可以在瀏覽器中預覽電子郵件訊息。當使用 Sail 時，Mailpit 的預設主機為 mailpit，可透過 1025 連接埠存取

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

當 Sail 執行時，您可以透過以下網址存取 Mailpit 網頁介面：https://127.0.0.1:8025

容器 CLI

有時您可能希望在應用程式的容器中啟動 Bash 工作階段。您可以使用 shell 命令連線到應用程式的容器，讓您可以檢查其檔案和已安裝的服務，以及在容器內執行任意 Shell 命令

sail shell
 
sail root-shell

要啟動新的 Laravel Tinker 工作階段，您可以執行 tinker 命令

sail tinker

PHP 版本

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

# 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 版本。此選項也在您的應用程式的 docker-compose.yml 檔案中定義

image: sail-8.2/app

在更新您應用程式的 docker-compose.yml 檔案之後，您應該重建您的容器映像檔

sail build --no-cache
 
sail up

Node 版本

Sail 預設會安裝 Node 20。要變更在建置映像檔時安裝的 Node 版本，您可以更新您應用程式 docker-compose.yml 檔案中 laravel.test 服務的 build.args 定義

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

在更新您應用程式的 docker-compose.yml 檔案之後，您應該重建您的容器映像檔

sail build --no-cache
 
sail up

分享您的網站

有時您可能需要公開共用您的網站，以便為同事預覽您的網站，或測試與您應用程式的 Webhook 整合。要共用您的網站，您可以使用 share 命令。在執行此命令之後，您將會收到一個隨機的 laravel-sail.site URL，您可以使用該 URL 來存取您的應用程式

sail share

當透過 share 命令共用您的網站時，您應該使用您應用程式 bootstrap/app.php 檔案中的 trustProxies 中介層方法，來設定應用程式的受信任 Proxy。否則，URL 產生協助程式 (例如 url 和 route) 將無法判斷 URL 產生期間應使用的正確 HTTP 主機

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

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

sail share --subdomain=my-sail-site
lightbulb

share 命令由 Expose 提供技術支援，Expose 是 BeyondCode 的開放原始碼通道服務。

使用 Xdebug 除錯

Laravel Sail 的 Docker 組態包含對 Xdebug 的支援，Xdebug 是 PHP 的熱門且功能強大的偵錯工具。為了啟用 Xdebug，您需要在應用程式的 .env 檔案中新增一些變數，以 設定 Xdebug。要啟用 Xdebug，您必須在啟動 Sail 之前設定適當的模式

SAIL_XDEBUG_MODE=develop,debug,coverage

Linux 主機 IP 組態

在內部，XDEBUG_CONFIG 環境變數定義為 client_host=host.docker.internal，以便為 Mac 和 Windows (WSL2) 正確設定 Xdebug。如果您的本機電腦執行 Linux，並且您使用 Docker 20.10+，則 host.docker.internal 可用，且不需要手動組態。

對於舊於 20.10 的 Docker 版本，Linux 上不支援 host.docker.internal，您需要手動定義主機 IP。若要執行此操作，請在您的 docker-compose.yml 檔案中定義自訂網路，為您的容器設定靜態 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 用法

當執行 Artisan 命令時，可以使用 sail debug 命令來啟動偵錯工作階段

# Run an Artisan command without Xdebug...
sail artisan migrate
 
# Run an Artisan command with Xdebug...
sail debug migrate

Xdebug 瀏覽器用法

若要在透過網頁瀏覽器與應用程式互動時偵錯您的應用程式，請依照 Xdebug 提供的指示，從網頁瀏覽器啟動 Xdebug 工作階段。

如果您使用 PhpStorm，請檢閱 JetBrains 關於 零組態偵錯 的文件。

exclamation

Laravel Sail 依賴 artisan serve 來服務您的應用程式。截至 Laravel 8.53.0 版本，artisan serve 命令僅接受 XDEBUG_CONFIG 和 XDEBUG_MODE 變數。舊版 Laravel (8.52.0 及更低版本) 不支援這些變數，並且不會接受偵錯連線。

自訂

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

sail artisan sail:publish

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

sail build --no-cache