サイトを更新しています。 数日間、レイアウトや翻訳に不具合が出ることがあります。ドキュメントは引き続きご利用いただけます。表示が崩れている場合は、後ほど再読み込みしてください。

ドキュメント
L Laravel ✓ L intervention/image ✓
10.x ✓
🇷🇺 Русский ✓🇪🇸 Español ✓🇯🇵 日本語 ✓
ログイン
ホーム Laravel 10.x Laravel Sail

Laravel Sail

10.x 2026年3月7日

#はじめに

Laravel Sail は、Laravel のデフォルト Docker 開発環境とやり取りするための軽量なコマンドラインインターフェイスです。Sail を使うことで、Docker の知識がなくても PHP、MySQL、Redis を使った Laravel アプリケーションの構築を簡単に始められます。

Sail の中核は、プロジェクトのルートにある docker-compose.yml ファイルと sail スクリプトです。sail スクリプトは、docker-compose.yml で定義された Docker コンテナと便利にやり取りできる CLI を提供します。

Laravel Sail は macOS、Linux、Windows（WSL2 経由）でサポートされています。

#インストールとセットアップ

Laravel Sail は新規 Laravel アプリケーションに自動的にインストールされるため、すぐに使い始められます。新しい Laravel アプリケーションの作成方法は、OS ごとの Laravel のインストールドキュメントをご覧ください。インストール時に、Sail がサポートするどのサービスを利用するか選択します。

#既存アプリケーションへの Sail のインストール

既存の Laravel アプリケーションで Sail を使いたい場合は、Composer パッケージマネージャーで Sail をインストールできます。もちろん、これらの手順は既存のローカル開発環境で Composer 依存関係をインストールできることが前提です。

composer require laravel/sail --dev

Sail をインストールしたら、sail:install Artisan コマンドを実行できます。このコマンドは Sail の docker-compose.yml ファイルをアプリケーションのルートに公開し、Docker サービスに接続するために必要な環境変数を .env ファイルに追加します。

php artisan sail:install

最後に Sail を起動できます。Sail の使い方をさらに学ぶには、このドキュメントの続きをお読みください。

./vendor/bin/sail up
Внимание

Linux で Docker Desktop を使っている場合は、docker context use default コマンドを実行して default Docker コンテキストを使うべきです。

#追加サービスの導入

既存の 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 コマンドは新規 Laravel アプリケーションに含まれる vendor/bin/sail スクリプトを使って呼び出します。

./vendor/bin/sail up

しかし、毎回 vendor/bin/sail と入力する代わりに、Sail コマンドを簡単に実行できるシェルエイリアスを設定することをおすすめします。

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

このエイリアスを常に使えるようにするには、~/.zshrc や ~/.bashrc などのホームディレクトリのシェル設定ファイルに追加し、シェルを再起動してください。

シェルエイリアスを設定すれば、単に sail と入力するだけで Sail コマンドを実行できます。このドキュメントの例はすべて、このエイリアスが設定されている前提で説明します。

sail up

#Sail の起動と停止

Laravel Sail の docker-compose.yml ファイルは、Laravel アプリケーション構築に必要な複数の Docker コンテナを定義しています。これらのコンテナはすべて docker-compose.yml の services 設定内にあります。laravel.test コンテナはアプリケーションを提供する主要なコンテナです。

Sail を起動する前に、ローカルで他のウェブサーバーやデータベースが動作していないことを確認してください。アプリケーションの docker-compose.yml に定義されたすべての 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 ドキュメントでは、Sail を使わずに Composer、Artisan、Node / NPM コマンドを実行する例がよく出てきます。 それらはローカルにこれらのツールがインストールされていることを前提としています。Sail をローカル開発環境で使う場合は、必ず 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 2.x がインストールされています。

sail composer require laravel/sanctum

#既存アプリケーションの Composer 依存関係のインストール

チームで開発している場合、あなたが最初に Laravel アプリケーションを作成したわけではないかもしれません。そのため、リポジトリをクローンしただけでは Sail を含む Composer 依存関係はインストールされていません。

アプリケーションのディレクトリに移動して、以下のコマンドを実行することで依存関係をインストールできます。このコマンドは PHP と Composer を含む小さな Docker コンテナを使って依存関係をインストールします。

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

laravelsail/phpXX-composer イメージを使う場合は、アプリケーションで使う予定の PHP バージョン（80、81、82、83）を使うべきです。

#Artisan コマンドの実行

Laravel の Artisan コマンドは artisan コマンドで実行できます。

sail artisan queue:work

#Node / NPM コマンドの実行

Node コマンドは node、NPM コマンドは npm で実行できます。

sail node --version

sail npm run dev

必要に応じて、NPM の代わりに Yarn を使うこともできます。

sail yarn

#データベースとの連携

#MySQL

アプリケーションの docker-compose.yml ファイルには MySQL コンテナの設定があります。このコンテナは Docker ボリューム を使っているため、コンテナを停止・再起動してもデータが保持されます。

さらに、MySQL コンテナが初めて起動するときに2つのデータベースが作成されます。1つは DB_DATABASE 環境変数の値を名前にしたローカル開発用データベース、もう1つは testing という名前のテスト用データベースで、テストが開発データに影響を与えないようにします。

コンテナを起動したら、アプリケーションの .env ファイルで DB_HOST 環境変数を mysql に設定して MySQL に接続できます。

ローカルマシンからアプリケーションの MySQL データベースに接続するには、TablePlus のような GUI データベース管理ツールを使えます。デフォルトでは MySQL は localhost のポート 3306 でアクセス可能で、認証情報は DB_USERNAME と DB_PASSWORD 環境変数の値に対応します。あるいは root ユーザーとして接続することもでき、その場合もパスワードは DB_PASSWORD の値を使います。

#Redis

アプリケーションの docker-compose.yml ファイルには Redis コンテナの設定もあります。このコンテナも Docker ボリューム を使っているため、停止・再起動しても Redis のデータが保持されます。コンテナを起動したら、アプリケーションの .env ファイルで REDIS_HOST 環境変数を redis に設定して Redis に接続できます。

ローカルマシンからアプリケーションの Redis データベースに接続するには、TablePlus のような GUI データベース管理ツールを使えます。デフォルトでは Redis は localhost のポート 6379 でアクセス可能です。

#Meilisearch

Sail インストール時に Meilisearch サービスを選択した場合、docker-compose.yml にこの強力な検索エンジンの設定が追加されます。Meilisearch は Laravel Scout と互換性があります。コンテナを起動したら、アプリケーションの MEILISEARCH_HOST 環境変数を http://meilisearch:7700 に設定して接続できます。

ローカルマシンからは、ブラウザで http://localhost:7700 にアクセスして Meilisearch のウェブ管理パネルを利用できます。

#Typesense

Sail インストール時に Typesense サービスを選択した場合、docker-compose.yml にこの高速なオープンソース検索エンジンの設定が追加されます。Typesense は Laravel Scout とネイティブに統合されています。コンテナを起動したら、以下の環境変数を設定して Typesense に接続できます。

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

ローカルマシンからは、http://localhost:8108 で Typesense の API にアクセスできます。

#ファイルストレージ

本番環境で Amazon S3 を使ってファイルを保存する場合、Sail インストール時に MinIO サービスを導入すると便利です。MinIO は S3 互換の API を提供し、本番の S3 環境に「テスト」用バケットを作らずにローカルで Laravel の s3 ファイルストレージドライバーを使って開発できます。MinIO を選択すると、docker-compose.yml に MinIO の設定が追加されます。

デフォルトでは、アプリケーションの filesystems 設定ファイルに s3 ディスクの設定が既に含まれています。このディスクを使って Amazon S3 とやり取りするだけでなく、環境変数を変更するだけで MinIO のような S3 互換のファイルストレージサービスとも連携できます。例えば、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=http://localhost:9000/local

バケットは http://localhost:8900 で利用可能な MinIO コンソールから作成できます。MinIO コンソールのデフォルトのユーザー名は sail、パスワードは password です。

Внимание

MinIO 使用時は、temporaryUrl メソッドによる一時的なストレージ URL の生成はサポートされていません。

#テストの実行

Laravel は標準で優れたテストサポートを提供しており、Sail の test コマンドを使ってアプリケーションの機能テストやユニットテストを実行できます。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 サービスは seleniarm/standalone-chromium イメージを使う必要があります。

selenium:
    image: 'seleniarm/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 のウェブインターフェイスに http://localhost:8025 からアクセスできます。

#コンテナ CLI

アプリケーションのコンテナ内で Bash セッションを開始したい場合があります。shell コマンドを使うと、コンテナに接続してファイルやインストール済みサービスを調査したり、任意のシェルコマンドを実行できます。

sail shell

sail root-shell

新しい Laravel Tinker セッションを開始するには、tinker コマンドを実行してください。

sail tinker

#PHP バージョン

Sail は現在、PHP 8.3、8.2、8.1、8.0 でアプリケーションを提供できます。デフォルトの PHP バージョンは PHP 8.3 です。使用する PHP バージョンを変更するには、アプリケーションの docker-compose.yml ファイル内の laravel.test コンテナの build 定義を更新してください。

# 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

さらに、アプリケーションで使用する PHP バージョンに合わせて image 名を更新することもできます。このオプションもアプリケーションの docker-compose.yml ファイルで定義されています。

image: sail-8.1/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 が発行されます。

sail share

share コマンドでサイトを共有する場合は、TrustProxies ミドルウェアでアプリケーションの信頼済みプロキシを設定してください。そうしないと、url や route といった URL 生成ヘルパーが正しい HTTP ホストを判別できません。

/**
 * このアプリケーションの信頼済みプロキシです。
 *
 * @var array|string|null
 */
protected $proxies = '*';

共有サイトのサブドメインを指定したい場合は、share コマンド実行時に subdomain オプションを指定できます。

sail share --subdomain=my-sail-site
Примечание

share コマンドは、BeyondCode が提供するオープンソースのトンネリングサービス Expose によって動作しています。

#Xdebug を使ったデバッグ

Laravel Sail の Docker 設定には、PHP 用の人気で強力なデバッガーである Xdebug のサポートが含まれています。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 Engine 17.06.0+ と Compose 1.16.0+ を使っていることを確認してください。そうでない場合は、以下のようにこの環境変数を手動で定義する必要があります。

まず、以下のコマンドを実行して環境変数に追加する正しいホスト IP アドレスを特定してください。通常、<container-name> はアプリケーションを提供するコンテナ名で、多くの場合 _laravel.test_1 で終わります。

docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>

正しいホスト IP アドレスを取得したら、アプリケーションの .env ファイルに SAIL_XDEBUG_CONFIG 変数を定義してください。

SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"

#Xdebug の CLI での使い方

Artisan コマンド実行時にデバッグセッションを開始するには、sail debug コマンドを使います。

# Xdebug なしで Artisan コマンドを実行...
sail artisan migrate

# Xdebug ありで Artisan コマンドを実行...
sail debug migrate

#Xdebug のブラウザでの使い方

ブラウザ経由でアプリケーションを操作しながらデバッグするには、Xdebug が提供するブラウザからのデバッグセッション開始方法に従ってください。

PhpStorm を使っている場合は、JetBrain のゼロコンフィギュレーションデバッグに関するドキュメントを参照してください。

Внимание

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 のインストールをカスタマイズした後は、アプリケーションの docker-compose.yml ファイルでアプリケーションコンテナのイメージ名を変更するとよいでしょう。その後、build コマンドでコンテナを再ビルドしてください。複数の Laravel アプリケーションを同じマシンで開発する場合は、アプリケーションイメージに固有の名前を付けることが特に重要です。

sail build --no-cache
← 前へ
Laravel Reverb