---
title: "Laravel Sail: диагностика WSL2, прав доступа, портов, OPcache и Vite | DevSense"
description: "Решение частых проблем с Laravel Sail: синхронизация файлов в WSL2, права доступа к storage/vendor, конфликты портов FORWARD_*, устаревший кэш Docker, настройка OPcache и Xdebug, работа с Vite и Node."
faq:
- question: "Почему сборка фронтенда через Vite работает крайне медленно на Windows с WSL2?"
answer: "Обычно это связано с тем, что файлы проекта хранятся на файловой системе Windows (/mnt/c/...). Чтобы это исправить, перенесите проект на родную файловую систему Linux (например, в ~/projects/) внутри WSL2."
- question: "Как исправить ошибки прав доступа (permission denied) к директории storage?"
answer: "Выполните команду очистки кеша 'sail artisan cache:clear' и настройте переменные окружения WWWUSER и WWWGROUP в файле .env так, чтобы они соответствовали ID вашего пользователя на хост-машине. Это сохранит правильные права доступа для файлов, сгенерированных контейнером."
- question: "Почему изменения в коде не отображаются внутри запущенного контейнера?"
answer: "Если изменения внесены в веб-часть, возможно, включен OPcache. Если это воркер очереди, он закешировал файлы фреймворка. Если вы обновили Dockerfile, необходимо запустить 'sail build --no-cache' и перезапустить контейнеры."
- question: "Как проверить список установленных PHP-расширений в среде Sail?"
answer: "Запустите команду 'sail exec laravel.test php -m', чтобы вывести список всех активных модулей PHP, работающих внутри контейнера, так как этот список может отличаться от вашей хост-системы."
---
# Sail: диагностика и производительность
Вчера ваше приложение работало идеально, но сегодня `sail up` выдает ошибку занятого порта, ассеты не компилируются через Vite, а запись в базу данных падает из-за ошибок прав доступа. Когда Sail ломается, дело редко в самом Laravel; почти всегда это конфликт между виртуализированной средой контейнера и файловой системой, сетью или процессами вашей хост-машины.
Слои виртуализации (особенно WSL2 на Windows) и пространства имен контейнеров вносят свои особенности. Понимание того, как диагностировать и обходить эти узкие места, критически важно для поддержания быстрого и плавного процесса разработки.
В этом руководстве мы собрали самые частые симптомы проблем с Sail, объяснили причины их возникновения и подготовили команды для их быстрого решения.
**Навигация:** [Все инструменты](../) · [Sail обзор](sail#what-sail-is) · [Базы данных](sail-databases#networking) · [Очереди](sail-queues#connections) · [Env и деплой](sail-env-deploy#forward-ports)
## Содержание
* [WSL2, Docker Desktop и синхронизация файлов](#wsl-filesync)
* [Права доступа, `storage` и `vendor`](#permissions)
* [Порт уже занят / `FORWARD_*`](#ports)
* [Различия окружений хоста и контейнера](#host-vs-container)
* [Устаревший код: пересборка и слои кэша](#rebuild)
* [OPcache и автозагрузка классов при разработке](#opcache)
* [Медленная работа Xdebug](#xdebug)
* [Vite, npm и Node: внутри против хост-машины](#frontend)
* [Логи и быстрая диагностика](#logs)
* [Когда нужно сбрасывать тома (потеря данных)](#volumes)
* [Частые ошибки](#common-mistakes)
* [Вопросы для самопроверки](#self-check)
---
## WSL2, Docker Desktop и синхронизация файлов
На Windows + WSL2 монтирование папок из разделов Windows (`/mnt/c/...`) внутрь контейнеров Linux приводит к огромным задержкам дискового ввода-вывода. Отслеживание файлов для автосборки (Vite, Webpack HMR) также перестает работать корректно.
Храните папки проектов исключительно **внутри родной файловой системы WSL** (например, `~/projects/...`). Открывайте их в VS Code через расширение **WSL**, чтобы компиляция и отслеживание изменений занимали миллисекунды, а не секунды.
---
## Права доступа, `storage` и `vendor`
Laravel требует прав на запись в папки `storage/` и `bootstrap/cache/`. Если Docker запускается от имени пользователя root, файлы, созданные внутри контейнеров, станут недоступными для изменения на вашем компьютере.
Проверьте права доступа изнутри контейнера:
```bash
# Terminal
sail exec laravel.test ls -la storage bootstrap/cache
```
> [!NOTE]
> **UID и GID маппинг**
> На Linux-системах настройте переменные `WWWUSER` и `WWWGROUP` в вашем файле `.env`, чтобы они соответствовали вашему локальному пользователю:
> ```dotenv
> # .env
> WWWUSER=1000
> WWWGROUP=1000
> ```
> Перезапустите Sail после внесения изменений.
---
## Порт уже занят / `FORWARD_*`
Если служба на вашем компьютере (например, локально установленный MySQL или другой запущенный проект Sail) использует порты `3306` или `80`, вы увидите ошибку `address already in use`.
Задайте альтернативные порты в вашем `.env`:
```dotenv
# .env
APP_PORT=8081
FORWARD_DB_PORT=3307
FORWARD_REDIS_PORT=6380
```
Выполните `sail down && sail up -d` для применения изменений.
---
## Различия окружений хоста и контейнера
Частая ошибка — выполнение команд вроде `php artisan migrate` или `composer install` напрямую в терминале вашего компьютера. Если версия PHP на компьютере отличается или на нем нет необходимых расширений (например, `redis` или `mongodb`), команда завершится ошибкой или повредит ваш файл `composer.lock`.
- **Хост (Плохо):** `composer install`
- **Sail (Хорошо):** `sail composer install`
---
## Устаревший код: пересборка и слои кэша
Если вы внесли изменения в опубликованные Docker-файлы (установили пакет через `apt` или расширение PHP через `pecl`), обычный перезапуск `sail up` не применит их, так как Docker использует кэшированные слои образов.
Принудительно пересоберите образы без использования кэша:
```bash
# Terminal
sail build --no-cache
sail up -d
```
---
## OPcache и автозагрузка классов при разработке
Если изменения в коде не отображаются в браузере, проверьте, не включен ли OPcache в конфигурации PHP контейнера. Во время разработки OPcache должен проверять временные метки файлов при каждом запросе.
Убедитесь, что в конфигурации PHP контейнера заданы следующие параметры:
```ini
# php.ini
opcache.validate_timestamps=1
opcache.revalidate_freq=0
```
При возникновении ошибок отсутствия классов после их перемещения запустите `sail composer dump-autoload`.
---
## Медленная работа Xdebug
Xdebug создает накладные расходы при выполнении каждого запроса. Отключайте его, когда не занимаетесь активной отладкой по шагам:
```dotenv
# .env
SAIL_XDEBUG_MODE=off
```
Перезапустите Sail: `sail down && sail up -d`.
---
## Vite, npm и Node: внутри против хост-машины
Вы можете компилировать фронтенд как на вашем компьютере, так и внутри контейнеров Sail.
- **Сборка на хосте (Быстрее всего):** Запустите `npm run dev` в локальном терминале.
- **Сборка в контейнере (Без настроек):** Запустите `sail npm run dev`.
Убедитесь, что параметры `APP_URL` и порты Vite совпадают, иначе в консоли браузера возникнут ошибки подключения к сокету HMR.
---
## Логи и быстрая диагностика
Используйте эти команды для проверки состояния контейнеров и модулей PHP:
```bash
# Terminal
sail logs -f laravel.test
docker compose ps
sail exec laravel.test php -v
sail exec laravel.test php -m
```
---
## Когда нужно сбрасывать тома (потеря данных)
Если локальная база данных повреждена или изменения схемы нарушили ее работу, сбросьте том. Помните: **`sail down -v` безвозвратно удаляет все таблицы баз данных и ключи Redis.**
Чтобы безопасно очистить только один конкретный том:
1. Выведите список томов: `docker volume ls`
2. Удалите нужный том: `docker volume rm <имя_тома>`
---
## ⚠️ Частые ошибки
**1. Монтирование файлов из разделов Windows в WSL2**
Хранение папки проекта в `C:/Users/...` при запуске Sail через WSL2. Это снижает скорость файловых операций до 10 раз.
*Решение:* Перенесите файлы в родную директорию Linux, например, `\\wsl$\Ubuntu\home\ubuntu\projects\`.
**2. Отсутствие расширений PHP в контейнере**
Запуск миграций, требующих драйвера PostgreSQL, когда PHP-контейнер не был собран с поддержкой pgsql.
*Решение:* Проверьте список активных модулей через `sail exec laravel.test php -m`. При необходимости опубликуйте Dockerfiles и пересоберите образы.
**3. Конфликты портов на localhost**
Запуск двух приложений Sail одновременно без изменения портов в `.env` одного из них.
*Решение:* Настройте уникальные значения `APP_PORT` и `FORWARD_*` в `.env` для каждого проекта.
---
## 🧠 Вопросы для самопроверки
1. **Почему файлы проектов в WSL2 не стоит хранить по пути `/mnt/c/`?**
2. **Какую команду нужно выполнить для пересборки образов Sail после изменения опубликованного Dockerfile?**
3. **Верно ли утверждение? Запуск `composer install` в терминале хост-машины безопасен, если версии PHP на компьютере и в Sail совпадают.**
4. **Как отключить Xdebug в Sail для предотвращения замедления работы приложения, когда он не используется?**
Показать ответы
1. Работа с файлами через границу файловой системы Windows (`/mnt/c/`) требует дополнительных уровней трансляции виртуализации, что критически замедляет операции чтения-записи и ломает отслеживание изменений.
2. Выполните команду `sail build --no-cache`, а затем перезапустите контейнеры через `sail up -d`.
3. **Неверно.** Даже при совпадении версий PHP на вашем компьютере могут отсутствовать необходимые компиляторы или PHP-расширения, которые установлены в контейнере. Всегда запускайте команды через префикс `sail`.
4. Установите `SAIL_XDEBUG_MODE=off` в файле `.env` и перезапустите контейнеры Sail.