跳到內容

Laravel Sail

簡介

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

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

Laravel Sail 支援 macOS、Linux 和 Windows (透過 WSL2)。

安裝與設定

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

將 Sail 安裝到現有應用程式

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

1composer require laravel/sail --dev

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

1php artisan sail:install

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

1./vendor/bin/sail up

如果您使用的是 Linux 版 Docker Desktop，您應該使用 default Docker context，方法是執行以下指令：docker context use default。

新增額外服務

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

1php artisan sail:add

使用 Devcontainers

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

1php artisan sail:install --devcontainer

重建 Sail 映像檔

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

1docker compose down -v
2 
3sail build --no-cache
4 
5sail up

設定 Shell 別名

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

1./vendor/bin/sail up

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

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

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

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

1sail up

啟動與停止 Sail

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

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

1sail up

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

1sail up -d

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

若要停止所有容器，您可以直接按下 Control + C 來停止容器的執行。或者，如果容器在背景執行，您可以使用 stop 指令

1sail stop

執行指令

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

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

1# Running Artisan commands locally...
2php artisan queue:work
3 
4# Running Artisan commands within Laravel Sail...
5sail artisan queue:work

執行 PHP 指令

PHP 指令可以使用 php 指令執行。當然，這些指令將使用為您的應用程式設定的 PHP 版本執行。若要深入了解 Laravel Sail 可用的 PHP 版本，請查閱 PHP 版本文件

1sail php --version
2 
3sail php script.php

執行 Composer 指令

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

1sail composer require laravel/sanctum

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

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

您可以導航到應用程式的目錄並執行以下指令來安裝應用程式的相依性。此指令使用一個包含 PHP 和 Composer 的小型 Docker 容器來安裝應用程式的相依性

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

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

執行 Artisan 指令

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

1sail artisan queue:work

執行 Node / NPM 指令

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

1sail node --version
2 
3sail npm run dev

如果您願意，可以使用 Yarn 而不是 NPM

1sail yarn

與資料庫互動

MySQL

您可能已經注意到，您的應用程式的 docker-compose.yml 檔案包含 MySQL 容器的項目。此容器使用 Docker volume，以便即使在停止和重新啟動容器時，儲存在資料庫中的資料也會持續存在。

此外，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 容器的項目，該容器提供具有 Atlas 功能 (如搜尋索引) 的 MongoDB 文件資料庫。此容器使用 Docker volume，以便即使在停止和重新啟動容器時，儲存在資料庫中的資料也會持續存在。

容器啟動後，您可以透過將應用程式 .env 檔案中的 MONGODB_URI 環境變數設定為 mongodb://mongodb:27017 來連線到應用程式內的 MongoDB 執行個體。預設情況下已停用身份驗證，但您可以在啟動 mongodb 容器之前設定 MONGODB_USERNAME 和 MONGODB_PASSWORD 環境變數來啟用身份驗證。然後，將憑證新增到連線字串

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

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

若要從本機電腦連線到應用程式的 MongoDB 資料庫，您可以使用圖形介面，例如 Compass。預設情況下，MongoDB 資料庫可透過 localhost 埠 27017 存取。

Redis

您的應用程式的 docker-compose.yml 檔案也包含 Redis 容器的項目。此容器使用 Docker volume，以便即使在停止和重新啟動容器時，儲存在 Redis 執行個體中的資料也會持續存在。容器啟動後，您可以透過將應用程式 .env 檔案中的 REDIS_HOST 環境變數設定為 redis 來連線到應用程式內的 Redis 執行個體。

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

Valkey

如果您在安裝 Sail 時選擇安裝 Valkey 服務，您的應用程式的 docker-compose.yml 檔案將包含 Valkey 的項目。此容器使用 Docker volume，以便即使在停止和重新啟動容器時，儲存在 Valkey 執行個體中的資料也會持續存在。您可以透過將應用程式 .env 檔案中的 REDIS_HOST 環境變數設定為 valkey 來連線到應用程式中的此容器。

若要從本機電腦連線到應用程式的 Valkey 資料庫，您可以使用圖形化資料庫管理應用程式，例如 TablePlus。預設情況下，Valkey 資料庫可透過 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 執行個體

1TYPESENSE_HOST=typesense
2TYPESENSE_PORT=8108
3TYPESENSE_PROTOCOL=http
4TYPESENSE_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 時，您的檔案系統環境變數設定應定義如下

1FILESYSTEM_DISK=s3
2AWS_ACCESS_KEY_ID=sail
3AWS_SECRET_ACCESS_KEY=password
4AWS_DEFAULT_REGION=us-east-1
5AWS_BUCKET=local
6AWS_ENDPOINT=http://minio:9000
7AWS_USE_PATH_STYLE_ENDPOINT=true

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

1AWS_URL=https://127.0.0.1:9000/local

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

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

執行測試

Laravel 開箱即用地提供了出色的測試支援，您可以使用 Sail 的 test 指令來執行應用程式的功能和單元測試。Pest / PHPUnit 接受的任何 CLI 選項也可以傳遞給 test 指令

1sail test
2 
3sail test --group orders

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

1sail artisan test

預設情況下，Sail 將建立專用的 testing 資料庫，以便您的測試不會干擾資料庫的目前狀態。在預設的 Laravel 安裝中，Sail 也會設定您的 phpunit.xml 檔案，以便在執行測試時使用此資料庫

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

Laravel Dusk

Laravel Dusk 提供了一個富有表現力、易於使用的瀏覽器自動化和測試 API。感謝 Sail，您可以執行這些測試，而無需在本機電腦上安裝 Selenium 或其他工具。若要開始使用，請取消註解應用程式 docker-compose.yml 檔案中的 Selenium 服務

1selenium:
2    image: 'selenium/standalone-chrome'
3    extra_hosts:
4      - 'host.docker.internal:host-gateway'
5    volumes:
6        - '/dev/shm:/dev/shm'
7    networks:
8        - sail

接下來，請確保應用程式 docker-compose.yml 檔案中的 laravel.test 服務具有 selenium 的 depends_on 項目

1depends_on:
2    - mysql
3    - redis
4    - selenium

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

1sail dusk

Apple Silicon 上的 Selenium

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

1selenium:
2    image: 'selenium/standalone-chromium'
3    extra_hosts:
4        - 'host.docker.internal:host-gateway'
5    volumes:
6        - '/dev/shm:/dev/shm'
7    networks:
8        - sail

預覽電子郵件

Laravel Sail 的預設 docker-compose.yml 檔案包含 Mailpit 的服務項目。Mailpit 會攔截您的應用程式在本機開發期間傳送的電子郵件，並提供方便的網頁介面，以便您可以在瀏覽器中預覽電子郵件訊息。當使用 Sail 時，Mailpit 的預設主機是 mailpit，可透過埠 1025 存取

1MAIL_HOST=mailpit
2MAIL_PORT=1025
3MAIL_ENCRYPTION=null

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

容器 CLI

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

1sail shell
2 
3sail root-shell

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

1sail 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 定義

 1# PHP 8.4
 2context: ./vendor/laravel/sail/runtimes/8.4
 3 
 4# PHP 8.3
 5context: ./vendor/laravel/sail/runtimes/8.3
 6 
 7# PHP 8.2
 8context: ./vendor/laravel/sail/runtimes/8.2
 9 
10# PHP 8.1
11context: ./vendor/laravel/sail/runtimes/8.1
12 
13# PHP 8.0
14context: ./vendor/laravel/sail/runtimes/8.0

此外，您可能希望更新您的 image 名稱，以反映您的應用程式正在使用的 PHP 版本。此選項也在您的應用程式的 docker-compose.yml 檔案中定義

1image: sail-8.2/app

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

1sail build --no-cache
2 
3sail up

Node 版本

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

1build:
2    args:
3        WWWGROUP: '${WWWGROUP}'
4        NODE_VERSION: '18'

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

1sail build --no-cache
2 
3sail up

分享您的網站

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

1sail share

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

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

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

1sail share --subdomain=my-sail-site

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

使用 Xdebug 進行除錯

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

1SAIL_XDEBUG_MODE=develop,debug,coverage

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

1[xdebug]
2xdebug.mode=${XDEBUG_MODE}

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

1sail build --no-cache

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

 1networks:
 2  custom_network:
 3    ipam:
 4      config:
 5        - subnet: 172.20.0.0/16
 6 
 7services:
 8  laravel.test:
 9    networks:
10      custom_network:
11        ipv4_address: 172.20.0.2

設定靜態 IP 後，請在應用程式的 .env 檔案中定義 SAIL_XDEBUG_CONFIG 變數

1SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Xdebug CLI 用法

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

1# Run an Artisan command without Xdebug...
2sail artisan migrate
3 
4# Run an Artisan command with Xdebug...
5sail debug migrate

Xdebug 瀏覽器用法

若要在透過網頁瀏覽器與應用程式互動時除錯您的應用程式，請遵循 Xdebug 提供的從網頁瀏覽器啟動 Xdebug 工作階段的說明。

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

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

自訂

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

1sail artisan sail:publish

執行此命令後，Laravel Sail 使用的 Dockerfile 和其他設定檔將會被放置在你的應用程式根目錄中的 docker 目錄內。在自訂你的 Sail 安裝後，你可能會希望更改應用程式容器的映像檔名稱，這可以在你的應用程式的 docker-compose.yml 檔案中進行。這麼做之後，使用 build 命令重建你的應用程式容器。為應用程式映像檔指定唯一名稱尤其重要，特別是當你使用 Sail 在單一機器上開發多個 Laravel 應用程式時。

1sail build --no-cache

Laravel 是最有效率的方式來
建構、部署和監控軟體。

產品

套件

資源