Деплой Laravel на сервер: команды, конфиг и ошибки
Деплой Laravel на сервер сводится к переносу кода, установке зависимостей, миграциям и настройке nginx с PHP-FPM. На Ubuntu 24.04 это выполняется набором команд git, composer и artisan, а веб-сервер отдаёт сайт из каталога public.
Что такое деплой Laravel и как он работает на сервере
Деплой Laravel на сервер означает, что код приложения оказывается в каталоге на VPS, зависимости ставятся через Composer, а nginx передаёт PHP-запросы в PHP-FPM. Точка входа у Laravel одна: файл public/index.php, поэтому корень сайта в nginx указывает на public, а не на корень проекта. База данных и кэш настраиваются в .env, который на сервере создаётся отдельно и не хранится в git.
Подготовка сервера: PHP 8.3, Composer, MySQL и nginx
На чистом Ubuntu 24.04 установите PHP 8.3 с расширениями, Composer, MySQL 8 и nginx. Для Laravel нужны расширения mbstring, xml, curl, zip, mysql и bcmath. После установки проверьте версии команд php -v и composer -V.
sudo apt update
sudo apt install -y nginx mysql-server php8.3-fpm php8.3-cli php8.3-mysql php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-bcmath unzip git
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
php -v
composer -V
Клонирование кода и установка зависимостей
Код забирается из репозитория в каталог /var/www/example.com. Для production ставьте зависимости без dev-пакетов и с оптимизированным автозагрузчиком. Если в проекте есть фронтенд на Vite, соберите его через npm ci и npm run build.
cd /var/www
sudo git clone git@github.com:user/app.git example.com
cd /var/www/example.com
composer install --no-dev --optimize-autoloader
npm ci
npm run build
Настройка.env и миграции базы данных
Скопируйте .env.example в .env и заполните доступы к MySQL 8: хост 127.0.0.1, имя базы, пользователя и пароль. Сгенерируйте ключ приложения командой php artisan key:generate. Миграции на сервере запускаются с флагом --force, иначе artisan в production попросит подтверждение.
cd /var/www/example.com
cp .env.example .env
php artisan key:generate
php artisan migrate --force
php artisan optimize
Конфиг nginx для Laravel
Сайт nginx должен смотреть в public и передавать PHP в сокет PHP-FPM 8.3. Директива try_files отдаёт существующие файлы, а остальное передаёт в index.php. Конфиг кладётся в /etc/nginx/sites-available/example.com и включается символической ссылкой в sites-enabled.
server {
listen 80;
server_name example.com;
root /var/www/example.com/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}
location ~ /\.ht {
deny all;
}
}
Права на storage и bootstrap/cache
PHP-FPM работает от пользователя www-data, поэтому каталоги storage и bootstrap/cache должны быть доступны на запись. Владельцем этих каталогов сделайте www-data. После смены прав проверьте, что логи и кэш создаются без ошибок Permission denied.
cd /var/www/example.com
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
Включение сайта и проверка конфигурации
Симлинк включает сайт, после чего проверьте синтаксис nginx командой sudo nginx -t и перезагрузите сервис. Если конфиг верный, nginx -t выведет syntax is ok и test is successful. Откройте сайт по IP или домену и убедитесь, что Laravel отвечает без 500.
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo systemctl restart php8.3-fpm
Очереди и перезапуск воркеров после деплоя
Если приложение использует очереди, после каждого деплоя перезапускайте воркеры, чтобы они подхватили новый код. Команда php artisan queue:restart завершает текущие задания и запускает обработку заново. Сам воркер держите под supervisor или systemd, иначе он остановится при выходе из SSH.
cd /var/www/example.com
php artisan queue:restart
Частые ошибки
-
Корень сайта в nginx указывает на корень проекта, а не на
public, и.envдоступен по URL.Исправьте
rootна/var/www/example.com/publicи перезагрузите nginx послеsudo nginx -t. -
Миграции запускают без
--force, и в production artisan ждёт подтверждения, деплой зависает.Выполняйте
php artisan migrate --forceв неинтерактивном режиме. -
Каталоги
storageиbootstrap/cacheпринадлежат root, PHP-FPM не может писать логи и кэш.Выполните
sudo chown -R www-data:www-data storage bootstrap/cacheи проверьте права775. -
После деплоя не перезапущены воркеры очередей, и они работают со старым кодом.
Запустите
php artisan queue:restartсразу после обновления кода.
Deploykin
Как это делается в Deploykin
В Deploykin сайт обновляется после пуша в GitHub: панель запускает deploy-скрипт с миграциями и кэшами, на тарифе Про без простоя. Каждый релиз остаётся в истории, откат делается в один клик.
7 дней бесплатно на тарифе Про, без привязки карты.
Вопросы и ответы
Какие команды выполнить для деплоя Laravel на сервер?
Клонируйте код, выполните composer install --no-dev --optimize-autoloader, настройте .env, запустите php artisan migrate --force и php artisan optimize, затем перезагрузите nginx и PHP-FPM.
Почему после деплоя Laravel отдаёт 500?
Смотрите storage/logs/laravel.log и /var/log/nginx/error.log. Частые причины: неверный .env, права на storage и отсутствие расширения php8.3-mysql.
Нужно ли собирать фронтенд на сервере?
Если в проекте Vite или Mix, да: выполните npm ci и npm run build на сервере или соберите заранее и перенесите каталог public/build.
Какой корень сайта указывать в nginx для Laravel?
Только каталог public: root /var/www/example.com/public;. Остальные файлы проекта не должны быть доступны из веба.
Всё по теме Деплой
Руководства по теме10
- Как развернуть сайт на VPS: Laravel и PHP на Ubuntu 24.04
- git pull rebase при деплое Laravel на VPS
- CI CD на Jenkins: деплой Laravel и PHP-сайтов на VPS
- git pull submodules при деплое Laravel на VPS
- Как отменить git pull на сервере: пошаговый разбор
- git fetch и git pull: различия и деплой Laravel на VPS
- Деплой PHP сайта на VPS: от чистого сервера до рабочего сайта
- Деплой Laravel на VPS: пошаговая инструкция с командами
- Настройка nginx для Laravel на Ubuntu 24.04
- git pull для деплоя Laravel на VPS: пошаговая настройка
Ошибки по теме6
- Ошибка 500 в Laravel: где искать причину и как исправить
- php artisan migrate ошибка: причины и исправление
- Ошибка composer install: как найти причину и исправить
- Ошибка git pull permission denied на VPS: как исправить
- Ошибка 419 Page Expired в Laravel: причины и исправление
- Ошибка 413 Request Entity Too Large в nginx: как исправить