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

<h2>Зміст</h2>

* [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)

---

<a id="wsl-filesync"></a>
## WSL2, Docker Desktop та синхронізація файлів

На Windows + WSL2 монтування папок із розділів Windows (`/mnt/c/...`) всередину контейнерів Linux призводить до величезних затримок дискового введення-виведення. Відстеження файлів для автозбірки (Vite, Webpack HMR) також перестає працювати коректно.

Зберігайте папки проєктів виключно **всередині рідної файлової системи WSL** (наприклад, `~/projects/...`). Відкривайте їх у VS Code через розширення **WSL**, щоб компіляція та відстеження змін займали мілісекунди, а не секунди.

---

<a id="permissions"></a>
## Права доступу, `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 після внесення змін.

---

<a id="ports"></a>
## Порт уже зайнятий / `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` для застосування змін.

---

<a id="host-vs-container"></a>
## Відмінності оточень хоста та контейнера

Часта помилка — виконання команд на кшталт `php artisan migrate` або `composer install` безпосередньо в терміналі вашого комп'ютера. Якщо версія PHP на комп'ютері відрізняється або на ньому немає необхідних розширень (наприклад, `redis` або `mongodb`), команда завершиться помилкою або пошкодить ваш файл `composer.lock`.

- **Хост (Погано):** `composer install`
- **Sail (Добре):** `sail composer install`

---

<a id="rebuild"></a>
## Застарілий код: перезбірка та шари кешу

Якщо ви внесли зміни в опубліковані Docker-файли (установили пакет через `apt` або розширення PHP через `pecl`), звичайний перезапуск `sail up` не застосує їх, оскільки Docker використовує кешовані шари образів.

Примусово перезберіть образи без використання кешу:

```bash
# Terminal
sail build --no-cache
sail up -d
```

---

<a id="opcache"></a>
## OPcache та автозавантаження класів при розробці

Якщо зміни в коді не відображаються в браузері, перевірте, чи не увімкнено OPcache в конфігурації PHP контейнера. Під час розробки OPcache повинен перевіряти часові мітки файлів при кожному запиті.

Переконайтеся, що в конфігурації PHP контейнера задані такі параметри:

```ini
# php.ini
opcache.validate_timestamps=1
opcache.revalidate_freq=0
```

При виникненні помилок відсутності класів після їх переміщення запустіть `sail composer dump-autoload`.

---

<a id="xdebug"></a>
## Повільна робота Xdebug

Xdebug створює накладні витрати при виконанні кожного запиту. Вимикайте його, коли не займаєтеся активним покроковим налагодженням:

```dotenv
# .env
SAIL_XDEBUG_MODE=off
```

Перезапустіть Sail: `sail down && sail up -d`.

---

<a id="frontend"></a>
## Vite, npm та Node: всередині проти хост-машини

Ви можете компілювати фронтенд як на вашому комп'ютері, так і всередині контейнерів Sail.

- **Збірка на хості (Найшвидше):** Запустіть `npm run dev` у локальному терміналі.
- **Збірка в контейнері (Без налаштувань):** Запустіть `sail npm run dev`.

Переконайтеся, що параметри `APP_URL` та порти Vite збігаються, інакше в консолі браузера виникнуть помилки підключення до сокету HMR.

---

<a id="logs"></a>
## Логи та швидка діагностика

Використовуйте ці команди для перевірки стану контейнерів та модулів PHP:

```bash
# Terminal
sail logs -f laravel.test
docker compose ps
sail exec laravel.test php -v
sail exec laravel.test php -m
```

---

<a id="volumes"></a>
## Коли потрібно скидати томи (втрата даних)

Якщо локальна база даних пошкоджена або зміни схеми порушили її роботу, скиньте том. Пам'ятайте: **`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 для запобігання уповільнення роботи застосунку, коли він не використовується?**

<details>
<summary><b>Показати відповіді</b></summary>

1. Робота з файлами через кордон файлової системи Windows (`/mnt/c/`) вимагає додаткових рівнів трансляції віртуалізації, що критично уповільнює операції читання-запису та ламає відстеження змін.
2. Виконайте команду `sail build --no-cache`, а потім перезапустіть контейнери через `sail up -d`.
3. **Невірно.** Навіть при збігу версій PHP на вашому комп'ютері можуть бути відсутні необхідні компілятори або PHP-розширення, які встановлені в контейнері. Завжди запускайте команди через префікс `sail`.
4. Встановіть `SAIL_XDEBUG_MODE=off` у файлі `.env` та перезапустіть контейнери Sail.
</details>