跳轉至內容

Laravel Sail

簡介

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

安裝與設定

Laravel Sail 會隨所有新的 Laravel 應用程式自動安裝，因此你可以立即開始使用它。

在現有應用程式中安裝 Sail

如果你有興趣在現有的 Laravel 應用程式中使用 Sail，只需使用 Composer 包管理器安裝 Sail 即可。當然，這些步驟假設你現有的本地開發環境允許安裝 Composer 依賴項。

1composer require laravel/sail --dev

安裝 Sail 後，你可以執行 sail:install Artisan 命令。該命令會將 Sail 的 compose.yaml 檔案釋出到應用程式的根目錄，並修改 .env 檔案以新增連線到 Docker 服務所需的環境變數。

1php artisan sail:install

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

1./vendor/bin/sail up

如果你正在使用 Linux 版 Docker Desktop，應透過執行以下命令來使用 default Docker 上下文：docker context use default。此外，如果在容器內遇到檔案許可權錯誤，可能需要將 SUPERVISOR_PHP_USER 環境變數設定為 root。

新增額外服務

如果你想向現有的 Sail 安裝中新增額外服務，可以執行 sail:add Artisan 命令。

1php artisan sail:add

使用開發容器 (Devcontainers)

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

然而，與其重複輸入 vendor/bin/sail 來執行 Sail 命令，你可能希望配置一個 shell 別名，以便更輕鬆地執行 Sail 命令。

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

為了確保該別名始終可用，你可以將其新增到主目錄下的 shell 配置檔案中，例如 ~/.zshrc 或 ~/.bashrc，然後重啟你的 shell。

一旦配置了 shell 別名，只需輸入 sail 即可執行 Sail 命令。本文件的後續示例將假設你已經配置了這個別名。

1sail up

啟動與停止 Sail

Laravel Sail 的 compose.yaml 檔案定義了多種協同工作的 Docker 容器，幫助你構建 Laravel 應用程式。這些容器中的每一個都是 compose.yaml 檔案 services 配置中的一個條目。laravel.test 容器是負責提供應用程式服務的主容器。

在啟動 Sail 之前，應確保本地計算機上沒有執行其他 Web 伺服器或資料庫。要啟動應用程式 compose.yaml 檔案中定義的所有 Docker 容器，請執行 up 命令。

1sail up

若要在後臺啟動所有 Docker 容器，可以以“分離”（detached）模式啟動 Sail。

1sail up -d

一旦應用程式的容器啟動，你就可以在 Web 瀏覽器中訪問專案：https://。

要停止所有容器，只需按 Control + C 停止容器執行。或者，如果容器在後臺執行，可以使用 stop 命令。

1sail stop

執行命令

使用 Laravel Sail 時，你的應用程式執行在 Docker 容器內，與本地計算機隔離。然而，Sail 提供了一種便捷的方式來針對你的應用程式執行各種命令，如任意 PHP 命令、Artisan 命令、Composer 命令和 Node / NPM 命令。

閱讀 Laravel 文件時，你經常會看到未提及 Sail 的 Composer、Artisan 和 Node / NPM 命令引用。 這些示例假設這些工具已安裝在你的本地計算機上。如果你使用 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

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

如你所見，應用程式的 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 環境變數以啟用身份驗證。然後，將憑據新增到連線字串中。

1MONGODB_USERNAME=user
2MONGODB_PASSWORD=laravel
3MONGODB_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 例項。

你可以從本地計算機透過在 Web 瀏覽器中導航至 https://:7700 來訪問 Meilisearch 的基於 Web 的管理面板。

Typesense

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

1TYPESENSE_HOST=typesense
2TYPESENSE_PORT=8108
3TYPESENSE_PROTOCOL=http
4TYPESENSE_API_KEY=xyz

從本地計算機，可以透過 https://:8108 訪問 Typesense 的 API。

檔案儲存

如果你計劃在生產環境執行應用程式時使用 Amazon S3 儲存檔案，則可能需要在安裝 Sail 時安裝 RustFS 服務。RustFS 提供了一個 S3 相容 API，你可以使用它在本地進行開發，利用 Laravel 的 s3 檔案儲存驅動，而無需在生產 S3 環境中建立“測試”儲存桶。如果在安裝 Sail 時選擇安裝 RustFS，應用程式的 compose.yaml 檔案中將新增 RustFS 配置部分。

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

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

執行測試

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 或其他工具即可執行這些測試。要開始使用，請取消註釋應用程式 compose.yaml 檔案中的 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

接下來，確保應用程式 compose.yaml 檔案中的 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 的預設 compose.yaml 檔案包含 Mailpit 的服務條目。Mailpit 會攔截在本地開發過程中由應用程式傳送的電子郵件，並提供一個便捷的 Web 介面，以便你在瀏覽器中預覽郵件。使用 Sail 時，Mailpit 的預設主機是 mailpit，可透過埠 1025 使用。

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

當 Sail 執行時，你可以透過以下網址訪問 Mailpit Web 介面：https://:8025。

容器 CLI

有時你可能希望在應用程式容器內啟動 Bash 會話。你可以使用 shell 命令連線到應用程式容器，從而檢查其中的檔案和已安裝的服務，並能在容器內執行任意 shell 命令。

1sail shell
2 
3sail root-shell

要啟動新的 Laravel Tinker 會話，可以執行 tinker 命令。

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

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

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

1image: sail-8.2/app

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

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

Node 版本

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

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

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

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

共享你的站點

有時你可能需要公開共享你的站點，以便向同事預覽站點，或者測試應用程式的 Webhook 整合。要共享站點，可以使用 share 命令。執行該命令後，你將獲得一個隨機的 laravel-sail.site URL，可用於訪問你的應用程式。

1sail share

透過 share 命令共享站點時，應使用應用程式 bootstrap/app.php 檔案中的 trustProxies 中介軟體方法配置應用程式的受信任代理。否則，URL 生成輔助函式（如 url 和 route）將無法確定生成 URL 時應使用的正確 HTTP 主機。

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

如果你想為共享站點選擇子域名，可以在執行 share 命令時提供 subdomain 選項。

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

share 命令由 Expose 提供支援，這是由 BeyondCode 開發的一款開源隧道服務。

使用 Xdebug 除錯

Laravel Sail 的 Docker 配置包含對 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，以便 Xdebug 針對 Mac 和 Windows (WSL2) 進行正確配置。如果你的本地計算機執行的是 Linux 且你使用的是 Docker 20.10+，則可以使用 host.docker.internal，無需手動配置。

對於早於 20.10 的 Docker 版本，Linux 不支援 host.docker.internal，你需要手動定義主機 IP。為此，請透過在 compose.yaml 檔案中定義自定義網路來為容器配置靜態 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 瀏覽器使用

若要在透過 Web 瀏覽器與應用程式互動時除錯應用程式，請遵循 Xdebug 提供的說明，從 Web 瀏覽器啟動 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 安裝後，你可能希望更改應用程式 compose.yaml 檔案中應用程式容器的映象名稱。完成此操作後，使用 build 命令重新構建應用程式容器。如果你在單臺機器上使用 Sail 開發多個 Laravel 應用程式，為應用程式映象分配唯一的名稱尤為重要。

1sail build --no-cache

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

產品

Packages

資源

合作伙伴