---
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 може да е активиран в PHP конфигурацията. Ако е работник за опашка, той е закеширал фреймуърка. Ако е промяна по Dockerfile, трябва да изпълните 'sail build --no-cache' и да рестартирате контейнерите."
- question: "Как да проверя какви разширения са заредени в моята Sail PHP среда?"
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`
---
## Остарял код: прекомпилиране и слоеве на кеша
Ако сте направили промени в публикуваните Dockerfiles (инсталирали сте пакет чрез `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.