Деплой Laravel на VPS: пошаговая инструкция с командами
Деплой Laravel на VPS сводится к восьми шагам: обновить код, поставить зависимости, собрать фронтенд, выдать права на storage и bootstrap/cache, прогнать миграции, собрать кэш и перезапустить очереди.
01Проверьте, что окружение готово
Деплой начинается на сервере, где уже работают nginx, PHP-FPM и MySQL. Убедитесь, что PHP 8.3 и нужные расширения на месте: php -v покажет версию, php -m список модулей. Для Laravel 11 и 12 нужны mbstring, xml, curl, zip, bcmath, intl и pdo_mysql. Если какого-то модуля нет, поставьте пакет php8.3-<имя> через apt.
php -v
php -m | grep -E 'mbstring|xml|curl|zip|bcmath|intl|pdo_mysql'
systemctl is-active nginx php8.3-fpm mysql
02Обновите код проекта
Заходите на сервер под пользователем, который владеет файлами сайта, и обновляйте код от него же. Клонирование по SSH требует ключа, добавленного в GitHub как deploy key, проверка ssh -T git@github.com. Если репозиторий уже склонирован, делайте git pull в каталоге проекта.
cd /var/www/example.com
git pull origin main
03Установите зависимости Composer
composer install --no-dev --optimize-autoloader ставит пакеты строго по composer.lock без dev-зависимостей и собирает оптимизированный автозагрузчик. Запускайте команду без sudo, от владельца проекта: иначе файлы в bootstrap/cache останутся за root, и PHP-FPM не сможет их перезаписать. Если Composer пишет Your requirements could not be resolved, в сообщении указано, какого расширения или версии PHP не хватает.
composer install --no-dev --optimize-autoloader
04Соберите фронтенд
Если в проекте есть package.json, поставьте зависимости и соберите ассеты. npm ci ставит пакеты по package-lock.json, npm run build собирает файлы в public/build. На сервере с малым объёмом памяти сборка может упасть с Killed: это OOM-killer, проверьте sudo dmesg -T | grep -i "killed process" и добавьте swap.
npm ci
npm run build
05Выдайте права на storage и bootstrap/cache
Владелец файлов проекта это пользователь, который деплоит. www-data пишет только в storage и bootstrap/cache, поэтому эти каталоги отдают ему группу. Остальные файлы www-data только читает, и chown -R www-data:www-data на весь сайт делать нельзя.
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R ug+rwX storage bootstrap/cache
06Прогоните миграции
php artisan migrate --force применяет миграции без интерактивного подтверждения. Флаг --force обязателен при APP_ENV=production, иначе команда ждёт ответа в терминале. Перед первым деплоем проверьте, что в .env задан APP_KEY: без него Laravel отдаёт No application encryption key has been specified.
php artisan migrate --force
07Соберите кэш конфига и маршрутов
php artisan optimize кэширует конфиг, маршруты, события и шаблоны. После этого env() вне файлов config/ возвращает null, а правка .env действует только после нового php artisan optimize или php artisan config:clear. Запускайте команду от владельца проекта, без sudo.
php artisan optimize
08Перезапустите очереди и PHP-FPM
php artisan queue:restart мягко перезапускает воркеры очередей, чтобы они подхватили новый код. Если в пуле FPM стоит opcache.validate_timestamps=0, новый код начнёт отдаваться только после перезагрузки службы. sudo systemctl reload php8.3-fpm применяет конфиг без остановки службы.
php artisan queue:restart
sudo systemctl reload php8.3-fpm
Частые ошибки
-
После
sudo chown -R www-data:www-data storage bootstrap/cacheкомандыcomposer installиphp artisan optimizeпадают у владельца проекта сPermission denied, а запущенные черезsudoоставляют файлы root.Верните владельца и группу:
sudo chown -R $USER:www-data storage bootstrap/cacheиsudo chmod -R ug+rwX storage bootstrap/cache. Команды деплоя запускайте безsudo. -
Сайт отдаёт 419 Page Expired: Laravel не нашёл в сессии CSRF-токен формы.
Проверьте
@csrfв форме и заголовокX-CSRF-TOKENв AJAX. СверьтеSESSION_DOMAINс доменом сайта, отключитеSESSION_SECURE_COOKIE=trueна сайте без HTTPS, проверьте таблицуsessionsпри драйвереdatabaseи пересоберите кэш черезphp artisan optimize. -
После правки
.envсайт продолжает работать со старыми значениями, аenv()внеconfig/возвращаетnull.Кэш конфига собран: выполните
php artisan optimizeилиphp artisan config:clearот владельца проекта. Значения из.envчитайте только в файлахconfig/. -
git pullпадает сerror: cannot open .git/FETCH_HEAD: Permission denied.Файлы репозитория принадлежат другому пользователю, обычно после
sudo git cloneилиchown -R www-dataна весь проект. Верните владельца:sudo chown -R $USER:$USER /var/www/example.com.
Deploykin
Как это делается в Deploykin
В Deploykin сайт обновляется после пуша в GitHub: панель запускает deploy-скрипт с миграциями и кэшами, на тарифе Про без простоя. Каждый релиз остаётся в истории, откат делается в один клик.
7 дней бесплатно на тарифе Про, без привязки карты.
Вопросы и ответы
Нужен ли --force у php artisan migrate при деплое?
Да, при APP_ENV=production без --force команда ждёт подтверждения в терминале и деплой зависает. С флагом миграции применяются сразу.
Почему после деплоя не видны изменения в .env?
Конфиг закэширован командой php artisan optimize. Выполните php artisan optimize или php artisan config:clear от владельца проекта, и новые значения вступят в силу.
Кому должны принадлежать файлы Laravel на сервере?
Пользователю, который деплоит. www-data получает группу и запись только на storage и bootstrap/cache, остальные файлы читает. chown -R www-data на весь сайт позволяет PHP переписать собственный код.
Что делать при ошибке 500 после деплоя?
Смотрите storage/logs/laravel.log: Laravel пишет туда причину. Частые случаи: нет APP_KEY, нет записи в storage у www-data, неверные DB_USERNAME или DB_PASSWORD в .env.
Как проверить, что nginx отдаёт именно public?
В конфиге сайта root должен указывать на /var/www/example.com/public, а location / содержать try_files $uri $uri/ /index.php?$query_string;. После правки выполните sudo nginx -t и sudo systemctl reload nginx.
Ещё по теме
- Руководство · Деплой Как развернуть сайт на VPS: Laravel и PHP на Ubuntu 24.04 Пошаговый деплой сайта на VPS: nginx, PHP 8.3, MySQL 8, git clone, composer install, миграции, права на storage и проверка через curl.
- Руководство · Деплой git pull rebase при деплое Laravel на VPS Как включить git pull rebase для деплоя Laravel на VPS: настройка git config, порядок команд, права на storage, проверка через git log и artisan.
- Руководство · Деплой CI CD на Jenkins: деплой Laravel и PHP-сайтов на VPS Пошаговая настройка CI CD на Jenkins для деплоя Laravel и PHP-сайтов на Ubuntu 24.04: команды сборки, права, миграции и проверка результата.
- Руководство · Деплой git pull submodules при деплое Laravel на VPS Как настроить git pull submodules при деплое Laravel на Ubuntu 24.04: клонирование с подмодулями, обновление, права, composer install и проверка результата.
- Руководство · Деплой Как отменить git pull на сервере: пошаговый разбор Как отменить git pull на Ubuntu 24.04: сохранить правки, вернуть коммиты через git reset и git revert, восстановить деплой Laravel и проверить результат.
- Руководство · Деплой git fetch и git pull: различия и деплой Laravel на VPS Чем git fetch отличается от git pull, как настроить деплой Laravel на Ubuntu 24.04: команды, права на storage, nginx и проверка работы сайта.
Деплой Laravel на сервер: команды, конфиг и ошибки: все материалы темы