К содержимому

Деплой Laravel на VPS: пошаговая инструкция с командами

Деплой Laravel на VPS сводится к восьми шагам: обновить код, поставить зависимости, собрать фронтенд, выдать права на storage и bootstrap/cache, прогнать миграции, собрать кэш и перезапустить очереди.

Руководство Деплой 4 мин чтения

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.

bash
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 в каталоге проекта.

bash
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 не хватает.

bash
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.

bash
npm ci
npm run build

05Выдайте права на storage и bootstrap/cache

Владелец файлов проекта это пользователь, который деплоит. www-data пишет только в storage и bootstrap/cache, поэтому эти каталоги отдают ему группу. Остальные файлы www-data только читает, и chown -R www-data:www-data на весь сайт делать нельзя.

bash
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.

bash
php artisan migrate --force

07Соберите кэш конфига и маршрутов

php artisan optimize кэширует конфиг, маршруты, события и шаблоны. После этого env() вне файлов config/ возвращает null, а правка .env действует только после нового php artisan optimize или php artisan config:clear. Запускайте команду от владельца проекта, без sudo.

bash
php artisan optimize

08Перезапустите очереди и PHP-FPM

php artisan queue:restart мягко перезапускает воркеры очередей, чтобы они подхватили новый код. Если в пуле FPM стоит opcache.validate_timestamps=0, новый код начнёт отдаваться только после перезагрузки службы. sudo systemctl reload php8.3-fpm применяет конфиг без остановки службы.

bash
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.

Ещё по теме

Деплой Laravel на сервер: команды, конфиг и ошибки: все материалы темы

Мы используем cookies и сервис веб-аналитики «Яндекс Метрика» (включая Вебвизор) для улучшения работы сайта. Подробности — в политике конфиденциальности.