Поиск
Справочник

php artisan optimize: кеш настроек, маршрутов и шаблонов Laravel

На каждый запрос Laravel читает файлы настроек, собирает список маршрутов и проверяет шаблоны. Команда php artisan optimize делает это один раз и сохраняет результат в файлы кеша — сайт отвечает быстрее. Обратная сторона: пока кеш собран, правки .env, маршрутов и шаблонов не действуют, пока кеш не собрать заново.

≈ 6 мин чтения
Содержание 11

Что сделать прямо сейчас

  1. Перейдите в папку проекта: cd /var/www/example.com.
  2. Соберите кеш от пользователя сайта: sudo -u www-data php artisan optimize.
  3. Проверьте, что всё собралось: php artisan about --only=cache.
  4. После каждой правки .env, маршрутов или шаблонов повторяйте шаг 2.

Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться). Права на папки storage и bootstrap/cache должны быть уже выданы — как.

Что делает optimize

Команда по очереди запускает четыре команды:

ЗадачаКомандаЧто сохраняетКуда
configconfig:cacheвсе файлы настроек и значения из .envbootstrap/cache/config.php
eventsevent:cacheкакие обработчики слушают какие событияbootstrap/cache/events.php
routesroute:cacheсписок маршрутовbootstrap/cache/routes-v7.php
viewsview:cacheшаблоны Blade, переведённые в PHPstorage/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.

Если нужна одна часть

НужноСобратьУдалить
настройки после правки .envphp artisan config:cachephp artisan config:clear
маршруты после правки routesphp artisan route:cachephp artisan route:clear
шаблоны после правки viewsphp artisan view:cachephp artisan view:clear
событияphp artisan event:cachephp 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
после правки .envsudo -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.

Источники

Сверено 13 ноября 2026 года.

Где попробовать. Команды из статьи безопаснее сначала повторить на отдельном тестовом сервере, а не на рабочем. Подойдёт VPS с Ubuntu, например Timeweb Cloud Реклама. АО «ТАЙМВЭБ», ИНН 7810353960. erid: CQH36pWzJpoBWKF332yG5h2XQ4cVubfBmkvqAitFqcpzWs. Как зайти на него после заказа — в статье Как подключиться к VPS по SSH.

Что почитать дальше