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

Laravel: руководство по установке и настройке

Laravel это PHP-фреймворк для веб-приложений, который ставится через Composer и работает на PHP 8.3 из Ubuntu 24.04. На сервере ему нужны nginx, PHP-FPM и база данных, а типичные сбои связаны с правами на storage, кэшем конфига и настройками пула FPM. Здесь собраны команды установки, конфигурация и разбор ошибок.

Опорная Laravel 4 мин чтения 21 материал в теме

Что такое 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.

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

bash
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, иначе изменения не подхватятся из-за кэша конфига.

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

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

bash
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-ключу пользователя, который деплоит.

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

bash
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/*']).

ini
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

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