php artisan optimize: кеш настроек, маршрутов и шаблонов Laravel
На каждый запрос Laravel читает файлы настроек, собирает список маршрутов и проверяет шаблоны. Команда php artisan optimize делает это один раз и сохраняет результат в файлы кеша — сайт отвечает быстрее. Обратная сторона: пока кеш собран, правки .env, маршрутов и шаблонов не действуют, пока кеш не собрать заново.
Содержание 11
Что сделать прямо сейчас
- Перейдите в папку проекта:
cd /var/www/example.com. - Соберите кеш от пользователя сайта:
sudo -u www-data php artisan optimize. - Проверьте, что всё собралось:
php artisan about --only=cache. - После каждой правки .env, маршрутов или шаблонов повторяйте шаг 2.
Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться). Права на папки storage и bootstrap/cache должны быть уже выданы — как.
Что делает optimize
Команда по очереди запускает четыре команды:
| Задача | Команда | Что сохраняет | Куда |
|---|---|---|---|
| config | config:cache | все файлы настроек и значения из .env | bootstrap/cache/config.php |
| events | event:cache | какие обработчики слушают какие события | bootstrap/cache/events.php |
| routes | route:cache | список маршрутов | bootstrap/cache/routes-v7.php |
| views | view:cache | шаблоны Blade, переведённые в PHP | storage/framework/views |
Ответ начинается строкой Caching framework bootstrap, configuration, and metadata., а дальше по строке на каждую задачу с пометкой DONE. Если в строке FAIL — запустите эту задачу отдельной командой, например sudo -u www-data php artisan route:cache: так будет виден текст ошибки.
Пакеты из папки vendor могут добавить к optimize свои команды — они выполнятся вместе с остальными.
Почему от пользователя www-data
Сайт работает от www-data и должен иметь возможность перезаписать файлы кеша. Если собрать кеш от своего пользователя, файлы в storage/framework/views и bootstrap/cache будут принадлежать вам. Тогда при следующей правке шаблона сайт не сможет их обновить и выдаст ошибку о правах.
sudo -u www-data php artisan optimizeЕсли кеш уже собран от своего пользователя или от root, верните права и соберите заново:
sudo chown -R www-data:www-data storage bootstrap/cache
sudo -u www-data php artisan optimizeКак убрать кеш
sudo -u www-data php artisan optimize:clearОтвет начинается строкой Clearing cached bootstrap files. Команда удаляет все четыре кеша и, кроме того:
| Команда внутри | Что удаляет |
|---|---|
cache:clear | все данные в кеше приложения — тот, что задан в CACHE_STORE |
clear-compiled | файлы services.php и packages.php в bootstrap/cache |
Учтите: cache:clear стирает всё, что приложение положило в кеш, например результаты тяжёлых запросов к базе. После него сайт какое-то время отвечает медленнее, пока кеш снова не наполнится.
После optimize:clear снова соберите кеш: sudo -u www-data php artisan optimize.
Если нужна одна часть
| Нужно | Собрать | Удалить |
|---|---|---|
| настройки после правки .env | php artisan config:cache | php artisan config:clear |
| маршруты после правки routes | php artisan route:cache | php artisan route:clear |
| шаблоны после правки views | php artisan view:cache | php artisan view:clear |
| события | php artisan event:cache | php artisan event:clear |
Команды запускайте так же, через sudo -u www-data.
Пропустить одну задачу в optimize можно ключом --except:
sudo -u www-data php artisan optimize --except=routesЧерез запятую можно перечислить несколько: --except=routes,views.
Когда собирать кеш
| Когда | Что выполнить |
|---|---|
| после выкладки нового кода | sudo -u www-data php artisan optimize |
| после правки .env | sudo -u www-data php artisan config:cache |
| при разработке на этом же сервере | кеш не собирать: php artisan optimize:clear |
Документация Laravel советует собирать кеш при каждой выкладке. Весь порядок обновления — в статье Выкладка обновлений.
Как проверить
php artisan about --only=cacheВ разделе Cache у строк Config, Events, Routes и Views должно стоять CACHED. Если NOT CACHED — эта часть не собрана. Подробнее — php artisan about.
Если после config:cache пропали настройки
После config:cache Laravel не читает .env. Функция env() в коде вне папки config вернёт пустое значение null. Документация Laravel требует вызывать env() только в файлах папки config, а в коде брать значения через config().
Пример: в контроллере написано env('PAYMENT_KEY'). До кеша работало, после — пусто. Перенесите строку в файл настроек, например config/services.php:
'payment' => [
'key' => env('PAYMENT_KEY'),
],А в коде читайте config('services.payment.key'). После правки соберите кеш заново.
Ошибки и как их исправить
| Что видите | Причина | Что делать |
|---|---|---|
| правка .env не действует | собран кеш настроек | sudo -u www-data php artisan config:cache |
| новый маршрут отвечает 404 | собран кеш маршрутов | sudo -u www-data php artisan route:cache |
Unable to prepare route … for serialization. Another route has already been assigned name … | у двух маршрутов одно имя | найдите имя в routes/web.php и routes/api.php и сделайте имена разными |
Your application doesn't have any routes. | в проекте нет ни одного маршрута | проверьте файлы в папке routes |
Your configuration files are not serializable. | в файле настроек замыкание или объект | оставьте в config только строки, числа и массивы |
env() в коде возвращает null | вызов env вне папки config | перенесите в config |
ошибка о правах в storage/framework/views | кеш собран не от www-data | верните права |
Please provide a valid cache path. | нет папок в storage/framework | Разбор |
Тексты сообщений сверены по исходному коду Laravel 13.42.0.
Источники
- Документация Laravel: Deployment — на английском: optimize, optimize:clear и отдельные кеши.
- Документация Laravel: Configuration — на английском: env() после config:cache.
- Исходный код команды optimize в Laravel 13.42.0 — на английском: четыре задачи и ключ --except.
- Исходный код команды optimize:clear в Laravel 13.42.0 — на английском: что удаляет команда.
- Исходный код Application в Laravel 13.42.0 — на английском: пути к файлам кеша.
Сверено 13 ноября 2026 года.
Что почитать дальше
- Laravel на серверевсе статьи о работе проекта на VPS.
- Файл .env на рабочем сайтекакие строки поменять.
- Выкладка обновленийпорядок команд при обновлении сайта.