Идёт обновление сайта. Несколько дней возможны сбои в оформлении и переводах. Документация работает — если страница выглядит сломанной, обновите её позже.

Документация
L Laravel ✓ L intervention/image ✓
10.x ✓
🇷🇺 Русский ✓🇪🇸 Español ✓🇯🇵 日本語 ✓
Войти
Главная Laravel 10.x Laravel Sail

Laravel Sail

10.x 7 мар 2026 г.

#Введение

Laravel Sail — это лёгкий интерфейс командной строки для работы с Docker-средой разработки Laravel по умолчанию. Sail предоставляет удобную отправную точку для создания Laravel-приложения с использованием PHP, MySQL и Redis без необходимости предварительного опыта работы с Docker.

В основе Sail лежат файл docker-compose.yml и скрипт sail, расположенные в корне вашего проекта. Скрипт sail предоставляет CLI с удобными методами для взаимодействия с Docker-контейнерами, определёнными в файле docker-compose.yml.

Laravel Sail поддерживается на macOS, Linux и Windows (через WSL2).

#Установка и настройка

Laravel Sail автоматически устанавливается во все новые Laravel-приложения, поэтому вы можете начать использовать его сразу. Чтобы узнать, как создать новое Laravel-приложение, обратитесь к документации по установке для вашей операционной системы. Во время установки вам будет предложено выбрать сервисы, поддерживаемые Sail, с которыми будет взаимодействовать ваше приложение.

#Установка Sail в существующие приложения

Если вы хотите использовать Sail с уже существующим Laravel-приложением, вы можете просто установить Sail через менеджер пакетов Composer. Разумеется, эти шаги предполагают, что ваша локальная среда разработки позволяет устанавливать зависимости Composer:

composer require laravel/sail --dev

После установки Sail вы можете выполнить Artisan-команду sail:install. Эта команда опубликует файл docker-compose.yml Sail в корне вашего приложения и изменит файл .env, добавив необходимые переменные окружения для подключения к Docker-сервисам:

php artisan sail:install

Наконец, вы можете запустить Sail. Чтобы продолжить изучение использования Sail, продолжайте читать оставшуюся часть этой документации:

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

Если вы используете Docker Desktop для Linux, следует использовать контекст Docker default, выполнив команду: docker context use default.

#Добавление дополнительных сервисов

Если вы хотите добавить дополнительный сервис в существующую установку Sail, вы можете выполнить Artisan-команду sail:add:

php artisan sail:add

#Использование Devcontainers

Если вы хотите разрабатывать внутри Devcontainer, вы можете передать опцию --devcontainer команде sail:install. Опция --devcontainer укажет команде sail:install опубликовать файл .devcontainer/devcontainer.json по умолчанию в корень вашего приложения:

php artisan sail:install --devcontainer

#Настройка псевдонима оболочки

По умолчанию команды Sail вызываются через скрипт vendor/bin/sail, который включён во все новые Laravel-приложения:

./vendor/bin/sail up

Однако вместо того, чтобы каждый раз вводить vendor/bin/sail для выполнения команд Sail, вы можете настроить псевдоним оболочки, который позволит запускать команды Sail проще:

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

Чтобы псевдоним всегда был доступен, добавьте его в файл конфигурации вашей оболочки в домашней директории, например ~/.zshrc или ~/.bashrc, а затем перезапустите оболочку.

После настройки псевдонима вы сможете выполнять команды Sail просто вводом sail. В дальнейшем в примерах документации предполагается, что вы настроили этот псевдоним:

sail up

#Запуск и остановка Sail

Файл docker-compose.yml Laravel Sail определяет множество Docker-контейнеров, которые работают вместе, чтобы помочь вам создавать Laravel-приложения. Каждый из этих контейнеров — это запись в конфигурации services вашего файла docker-compose.yml. Контейнер laravel.test является основным контейнером приложения, который обслуживает ваше приложение.

Перед запуском Sail убедитесь, что на вашем локальном компьютере не запущены другие веб-серверы или базы данных. Чтобы запустить все Docker-контейнеры, определённые в файле docker-compose.yml вашего приложения, выполните команду up:

sail up

Чтобы запустить все Docker-контейнеры в фоновом режиме, вы можете запустить Sail в режиме "detached":

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

# Запуск Artisan-команд внутри Laravel Sail...
sail artisan queue:work

#Выполнение PHP-команд

PHP-команды можно выполнять с помощью команды php. Разумеется, эти команды будут выполняться с использованием версии PHP, настроенной для вашего приложения. Чтобы узнать больше о версиях PHP, доступных в Laravel Sail, ознакомьтесь с документацией по версиям PHP:

sail php --version

sail php script.php

#Выполнение Composer-команд

Команды Composer можно выполнять с помощью команды composer. Контейнер приложения Laravel Sail включает установку Composer версии 2.x:

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/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

Если хотите, вы можете использовать Yarn вместо NPM:

sail yarn

#Работа с базами данных

#MySQL

Как вы могли заметить, в файле docker-compose.yml вашего приложения есть запись для контейнера MySQL. Этот контейнер использует Docker volume, чтобы данные в базе сохранялись даже при остановке и перезапуске контейнеров.

Кроме того, при первом запуске контейнера MySQL будут созданы две базы данных. Первая база данных называется в соответствии со значением переменной окружения DB_DATABASE и предназначена для локальной разработки. Вторая — специальная тестовая база с именем testing, которая гарантирует, что ваши тесты не повлияют на данные разработки.

После запуска контейнеров вы можете подключиться к экземпляру MySQL в вашем приложении, установив переменную окружения DB_HOST в файле .env вашего приложения в значение mysql.

Для подключения к базе MySQL вашего приложения с локальной машины вы можете использовать графическое приложение для управления базами данных, например TablePlus. По умолчанию база MySQL доступна на localhost порт 3306, а учётные данные соответствуют значениям переменных окружения DB_USERNAME и DB_PASSWORD. Либо можно подключиться как пользователь root, используя значение DB_PASSWORD в качестве пароля.

#Redis

В файле docker-compose.yml вашего приложения также есть запись для контейнера Redis. Этот контейнер использует Docker volume, чтобы данные Redis сохранялись даже при остановке и перезапуске контейнеров. После запуска контейнеров вы можете подключиться к экземпляру Redis в вашем приложении, установив переменную окружения REDIS_HOST в файле .env вашего приложения в значение redis.

Для подключения к базе Redis вашего приложения с локальной машины вы можете использовать графическое приложение для управления базами данных, например TablePlus. По умолчанию база Redis доступна на localhost порт 6379.

#Meilisearch

Если вы выбрали установку сервиса Meilisearch при установке Sail, в файле docker-compose.yml вашего приложения появится запись для этого мощного поискового движка, который совместим с Laravel Scout. После запуска контейнеров вы можете подключиться к экземпляру Meilisearch в вашем приложении, установив переменную окружения MEILISEARCH_HOST в значение http://meilisearch:7700.

С локальной машины вы можете получить доступ к веб-интерфейсу администрирования Meilisearch, перейдя в браузере по адресу http://localhost:7700.

#Typesense

Если вы выбрали установку сервиса Typesense при установке Sail, в файле docker-compose.yml вашего приложения появится запись для этого сверхбыстрого, открытого поискового движка, который нативно интегрирован с Laravel Scout. После запуска контейнеров вы можете подключиться к экземпляру Typesense в вашем приложении, установив следующие переменные окружения:

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

С локальной машины вы можете получить доступ к API Typesense по адресу http://localhost:8108.

#Хранение файлов

Если вы планируете использовать Amazon S3 для хранения файлов в продакшн-среде, возможно, вам стоит установить сервис MinIO при установке Sail. MinIO предоставляет совместимый с S3 API, который позволяет разрабатывать локально с использованием драйвера файловой системы Laravel s3 без создания "тестовых" бакетов в продакшн-окружении S3. Если вы выберете установку MinIO при установке Sail, в файл docker-compose.yml вашего приложения будет добавлен раздел конфигурации MinIO.

По умолчанию в конфигурационном файле 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

Чтобы интеграция Flysystem Laravel корректно генерировала URL при использовании MinIO, следует определить переменную окружения AWS_URL, чтобы она соответствовала локальному URL вашего приложения и включала имя бакета в пути URL:

AWS_URL=http://localhost:9000/local

Вы можете создавать бакеты через консоль MinIO, доступную по адресу http://localhost:8900. Имя пользователя по умолчанию — sail, а пароль — password.

Внимание

Генерация временных URL через метод temporaryUrl не поддерживается при использовании MinIO.

#Запуск тестов

Laravel предоставляет отличную поддержку тестирования из коробки, и вы можете использовать команду test Sail для запуска функциональных и модульных тестов вашего приложения. Любые опции CLI, поддерживаемые PHPUnit, также могут быть переданы команде test:

sail test

sail test --group orders

Команда test Sail эквивалентна выполнению Artisan-команды test:

sail artisan test

По умолчанию Sail создаёт отдельную базу данных testing, чтобы ваши тесты не влияли на текущее состояние базы данных. В стандартной установке Laravel Sail также настраивает файл phpunit.xml для использования этой базы данных при выполнении тестов:

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

#Laravel Dusk

Laravel Dusk предоставляет выразительный и простой в использовании API для автоматизации браузера и тестирования. Благодаря Sail вы можете запускать эти тесты без установки Selenium или других инструментов на локальном компьютере. Для начала раскомментируйте сервис Selenium в файле docker-compose.yml вашего приложения:

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

Затем убедитесь, что сервис laravel.test в файле docker-compose.yml вашего приложения содержит запись depends_on для selenium:

depends_on:
    - mysql
    - redis
    - selenium

Наконец, вы можете запустить набор тестов Dusk, запустив Sail и выполнив команду dusk:

sail dusk

#Selenium на Apple Silicon

Если на вашем локальном компьютере установлен процессор 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

#Просмотр писем

Файл docker-compose.yml Laravel Sail по умолчанию содержит запись сервиса для 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.3, 8.2, 8.1 или PHP 8.0. По умолчанию Sail использует PHP 8.3. Чтобы изменить версию PHP, используемую для запуска приложения, обновите определение build контейнера laravel.test в файле docker-compose.yml вашего приложения:

# 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.1/app

После обновления файла docker-compose.yml вашего приложения следует пересобрать образы контейнеров:

sail build --no-cache

sail up

#Версии Node

По умолчанию Sail устанавливает Node 20. Чтобы изменить версию Node, устанавливаемую при сборке образов, обновите определение build.args сервиса laravel.test в файле docker-compose.yml вашего приложения:

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

После обновления файла docker-compose.yml вашего приложения следует пересобрать образы контейнеров:

sail build --no-cache

sail up

#Общий доступ к сайту

Иногда нужно предоставить публичный доступ к вашему сайту, чтобы показать его коллеге или протестировать интеграции вебхуков с вашим приложением. Для этого можно использовать команду share. После её выполнения вам будет выдан случайный URL с доменом laravel-sail.site, по которому можно получить доступ к приложению:

sail share

При использовании команды share следует настроить доверенные прокси вашего приложения в промежуточном ПО TrustProxies. Иначе помощники генерации URL, такие как url и route, не смогут определить правильный HTTP-хост для генерации URL:

/**
 * Доверенные прокси для этого приложения.
 *
 * @var array|string|null
 */
protected $proxies = '*';

Если вы хотите выбрать поддомен для общего доступа к сайту, можете передать опцию subdomain при выполнении команды share:

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

Команда share работает на базе Expose, открытого сервиса туннелирования от BeyondCode.

#Отладка с Xdebug

Конфигурация Docker Laravel Sail включает поддержку Xdebug, популярного и мощного отладчика для PHP. Чтобы включить Xdebug, необходимо добавить несколько переменных в файл .env вашего приложения для настройки Xdebug. Для включения Xdebug нужно установить соответствующие режимы перед запуском Sail:

SAIL_XDEBUG_MODE=develop,debug,coverage

#Настройка IP хоста для Linux

Внутри контейнера переменная окружения XDEBUG_CONFIG определяется как client_host=host.docker.internal, чтобы Xdebug корректно работал на Mac и Windows (WSL2). Если ваша локальная машина работает под 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-адрес хоста, определите переменную SAIL_XDEBUG_CONFIG в файле .env вашего приложения:

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

#Использование Xdebug в CLI

Команду sail debug можно использовать для запуска сессии отладки при выполнении Artisan-команды:

# Запуск Artisan-команды без Xdebug...
sail artisan migrate

# Запуск Artisan-команды с Xdebug...
sail debug migrate

#Использование Xdebug в браузере

Чтобы отлаживать приложение при взаимодействии через веб-браузер, следуйте инструкциям Xdebug по запуску сессии Xdebug из браузера.

Если вы используете PhpStorm, ознакомьтесь с документацией JetBrains по отладке без настройки.

Внимание

Laravel Sail использует artisan serve для обслуживания приложения. Команда artisan serve принимает переменные XDEBUG_CONFIG и XDEBUG_MODE начиная с версии Laravel 8.53.0. В более старых версиях Laravel (8.52.0 и ниже) эти переменные не поддерживаются, и отладочные подключения не будут работать.

#Настройка

Поскольку Sail — это просто Docker, вы можете настраивать практически всё. Чтобы опубликовать собственные Dockerfile Sail, выполните команду sail:publish:

sail artisan sail:publish

После выполнения этой команды Dockerfile и другие конфигурационные файлы Laravel Sail будут размещены в директории docker в корне вашего приложения. После настройки Sail вы можете изменить имя образа приложения в файле docker-compose.yml вашего приложения. После этого пересоберите контейнеры с помощью команды build. Присвоение уникального имени образу приложения особенно важно, если вы используете Sail для разработки нескольких Laravel-приложений на одной машине:

sail build --no-cache
← Предыдущая
Laravel Reverb