Laravel: руководство по установке и настройке
Laravel это PHP-фреймворк для веб-приложений, который ставится через Composer и работает на PHP 8.3 из Ubuntu 24.04. На сервере ему нужны nginx, PHP-FPM и база данных, а типичные сбои связаны с правами на storage, кэшем конфига и настройками пула FPM. Здесь собраны команды установки, конфигурация и разбор ошибок.
Что такое Laravel и как он работает на сервере
Laravel это MVC-фреймворк на PHP: запрос приходит в public/index.php, проходит через middleware и маршруты, попадает в контроллер и возвращает ответ. Точка входа одна, поэтому в nginx root указывает на каталог public, а не на корень проекта. Версия Laravel 13 требует PHP 8.3 и выше, PHP 8.3 из Ubuntu 24.04 подходит. Версию проекта показывает php artisan --version.
php artisan --version
Установка Laravel на Ubuntu 24.04
Проект создают командой composer create-project laravel/laravel example.com. Для Laravel нужны расширения php8.3-mbstring, php8.3-xml, php8.3-curl, php8.3-zip, php8.3-bcmath, php8.3-intl и драйвер базы php8.3-mysql. После создания проекта задают APP_KEY командой php artisan key:generate и выполняют миграции php artisan migrate.
composer create-project laravel/laravel example.com
cd example.com
php artisan key:generate
php artisan migrate
Настройка.env и подключение MySQL
В свежем проекте Laravel по умолчанию DB_CONNECTION=sqlite, QUEUE_CONNECTION=database и CACHE_STORE=database. Для MySQL в .env ставят DB_CONNECTION=mysql и задают DB_HOST, DB_DATABASE, DB_USERNAME и DB_PASSWORD. После правки .env выполняют php artisan config:clear или php artisan optimize, иначе изменения не подхватятся из-за кэша конфига.
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=example
DB_USERNAME=example
DB_PASSWORD=secret
Настройка nginx и PHP-FPM
Для Laravel root в nginx смотрит в /var/www/example.com/public: .env и код вне public наружу не отдаются. Пул www из пакета PHP работает от www-data и слушает /run/php/php8.3-fpm.sock. Конфиг FPM проверяют командой sudo php-fpm8.3 -t, применяют через sudo systemctl reload php8.3-fpm.
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;
}
}
Права на файлы и каталоги
Владелец файлов проекта это пользователь, который деплоит. www-data пишет только в storage и bootstrap/cache через группу: sudo chown -R $USER:www-data storage bootstrap/cache и sudo chmod -R ug+rwX storage bootstrap/cache. Остальные файлы www-data только читает. Если сделать владельцем www-data, composer install и php artisan optimize упадут с Permission denied.
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R ug+rwX storage bootstrap/cache
Деплой Laravel: порядок команд
Команды деплоя идут в таком порядке: код, composer install --no-dev --optimize-autoloader, сборка фронтенда, права на storage и bootstrap/cache, php artisan migrate --force, php artisan optimize, php artisan queue:restart. Флаг --force у migrate нужен при APP_ENV=production, иначе команда ждёт подтверждения. Приватный репозиторий клонируют по SSH-ключу пользователя, который деплоит.
composer install --no-dev --optimize-autoloader
npm ci && npm run build
sudo chown -R $USER:www-data storage bootstrap/cache
php artisan migrate --force
php artisan optimize
php artisan queue:restart
Кэширование конфига и маршрутов
php artisan optimize кэширует конфиг, маршруты, события и шаблоны: config:cache, route:cache, event:cache и view:cache. После config:cache функция env() вне файлов config/ возвращает null, а правка .env действует только после нового php artisan optimize или php artisan config:clear. С opcache.validate_timestamps=0 новый код подхватывается только после sudo systemctl reload php8.3-fpm.
php artisan optimize
php artisan config:clear
sudo systemctl reload php8.3-fpm
Безопасность: APP_DEBUG, APP_KEY и CSRF
APP_DEBUG=true на рабочем сайте показывает посетителям пароли из .env, поэтому на сервере ставят APP_DEBUG=false. APP_KEY создают один раз командой php artisan key:generate: новый ключ разлогинивает всех и ломает зашифрованные данные, при переезде ключ переносят вместе с .env. В Laravel 11 и новее исключения CSRF задают в bootstrap/app.php через $middleware->validateCsrfTokens(except: ['stripe/*']).
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:...
Частые ошибки
-
Владельцем
storageиbootstrap/cacheсделалиwww-data, после чегоcomposer installиphp artisan optimizeпадают сPermission denied.Верните владельца проекта:
sudo chown -R $USER:www-data storage bootstrap/cacheиsudo chmod -R ug+rwX storage bootstrap/cache. Команды запускайте без sudo, от владельца проекта. -
После правки
.envна сервере значения не меняются, потому что конфиг закэширован командойphp artisan optimize.Выполните
php artisan config:clearилиphp artisan optimizeзаново. Помните, что послеconfig:cacheфункцияenv()вне файловconfig/возвращаетnull. -
На production вход в Filament заканчивается ошибкой 403, хотя пользователь создан.
Добавьте в модель
UserреализациюFilament\Models\Contracts\FilamentUserс методомcanAccessPanel(Panel $panel): bool, который возвращаетtrueдля нужных пользователей. -
Компоненты Livewire не работают, в логе nginx 404 на адрес вида
/livewire-<хеш>/livewire.min.js.Уберите отдельный location для
.jsсtry_files $uri =404;или добавьте исключение для пути/livewire-. Скрипт отдаёт Laravel, а не статический файл.
Deploykin
Как это делается в Deploykin
В Deploykin сайт на Laravel создаётся из панели: стек под приложение, key:generate и storage:link выполняются при создании, а доступы к базе сами попадают в .env. Деплой идёт без простоя, с миграциями и кэшами, а очереди держат демоны Horizon или Queue Worker.
7 дней бесплатно на тарифе Про, без привязки карты.
Вопросы и ответы
Какая версия PHP нужна для Laravel 13?
Laravel 13 требует PHP 8.3 и выше. PHP 8.3 из Ubuntu 24.04 подходит, отдельная установка не нужна.
Почему после деплоя Laravel отдаёт 500?
Смотрите storage/logs/laravel.log: при APP_DEBUG=false подробности есть только там. Частые причины: права на storage, неверные данные в .env или невыполненные миграции.
Как исправить 403 при входе в Filament на сервере?
Filament пускает в панель только при APP_ENV=local, если модель User не реализует FilamentUser. Добавьте интерфейс и метод canAccessPanel, возвращающий true.
Нужно ли запускать php artisan optimize после каждой правки .env?
Да, если конфиг закэширован. php artisan optimize пересобирает кэш, а php artisan config:clear его сбрасывает.
Всё по теме Laravel
Руководства по теме21
- PHP Laravel: пошаговая настройка проекта на Ubuntu 24.04
- Filament в Laravel: установка и настройка панели
- Laravel Livewire: установка и первый компонент на Ubuntu 24.04
- Laravel API: пошаговая настройка на Ubuntu 24.04
- Laravel Eloquent: настройка и проверка на Ubuntu 24.04
- Laravel install: установка фреймворка на Ubuntu 24.04
- Inertia Laravel: пошаговая настройка на Ubuntu 24.04
- Laravel Reverb: настройка на Ubuntu 24.04
- Laravel Sail: установка и запуск на Ubuntu 24.04
- Валидация в Laravel: пошаговая настройка на Ubuntu 24.04
- Laravel CMS: пошаговая настройка на Ubuntu 24.04
- Создание компонента Livewire в Laravel на Ubuntu 24.04
- Разработка сайта на Laravel на Ubuntu 24.04
- Laravel Scout: настройка поиска на Ubuntu 24.04
- Настройка laravel lang: файлы переводов и смена языка
- Laravel htaccess: настройка nginx вместо.htaccess
- Laravel observer: пошаговая настройка на Ubuntu 24.04
- Laravel Socialite: пошаговая настройка входа через провайдера
- Админ-панель Laravel на Filament: пошаговая настройка
- Laravel Debugbar: установка и проверка на Ubuntu 24.04
- Laravel Breeze: пошаговая настройка на Ubuntu 24.04