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

PHP Laravel: пошаговая настройка проекта на Ubuntu 24.04

Laravel это PHP-фреймворк для веб-приложений: маршруты, ORM Eloquent, шаблоны Blade и очереди в одном наборе пакетов. На Ubuntu 24.04 с PHP 8.3 проект создаётся одной командой Composer и запускается через встроенный сервер или nginx.

Руководство Laravel 3 мин чтения

01Проверьте PHP и Composer

Laravel 13 требует PHP 8.3 и выше, а Ubuntu 24.04 ставит именно PHP 8.3. Убедитесь, что установлены CLI, FPM и расширения, без которых Composer и Laravel не работают. Если пакетов нет, поставьте их одной командой apt.

bash
php -v
composer --version
sudo apt install php8.3-cli php8.3-fpm php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-bcmath php8.3-intl php8.3-mysql

02Создайте проект Laravel

Перейдите в каталог /var/www и создайте проект командой Composer. Каталог example.com станет корнем приложения. Версию фреймворка покажет php artisan --version.

bash
cd /var/www
composer create-project laravel/laravel example.com
cd example.com
php artisan --version

03Настройте.env и ключ приложения

Свежий проект использует SQLite, а для MySQL в .env меняют DB_CONNECTION и параметры подключения. Ключ шифрования создают один раз командой php artisan key:generate: без него Laravel отвечает ошибкой No application encryption key has been specified.. Базу example и пользователя создайте заранее в MySQL.

ini
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=example
DB_USERNAME=laravel
DB_PASSWORD=secret

04Создайте таблицы миграциями

Миграции создают таблицы users, sessions, cache и jobs, на которые рассчитаны настройки по умолчанию. На рабочем сервере с APP_ENV=production команда ждёт подтверждения, поэтому запускайте её с --force. Ошибку подключения к базе Laravel печатает сразу и пишет подробности в storage/logs/laravel.log.

bash
php artisan migrate --force

05Настройте nginx на каталог public

Для Laravel root в nginx смотрит в /var/www/example.com/public, тогда .env и код вне public не отдаются наружу. Все запросы, которых нет среди файлов, передаются в index.php. После правки проверьте конфиг и перезагрузите nginx.

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;
    }
}

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

Владелец файлов проекта это пользователь, который деплоит, а www-data пишет только в storage и bootstrap/cache через группу. Остальные файлы www-data только читает. Команды composer install и php artisan optimize запускайте без sudo от владельца проекта, иначе они упадут с Permission denied.

bash
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R ug+rwX storage bootstrap/cache

07Закэшируйте конфиг и маршруты

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

bash
php artisan optimize
php artisan route:list

08Проверьте, что приложение отвечает

Откройте http://example.com в браузере: должна открыться стартовая страница Laravel. Если видите 500, причину ищите в storage/logs/laravel.log, а в браузере при APP_DEBUG=false будет только общая страница. Ответ File not found. и запись Primary script unknown в логе nginx значат, что PHP-FPM не нашёл файл по SCRIPT_FILENAME: проверьте root и права на файлы.

bash
curl -I http://example.com
tail -n 50 storage/logs/laravel.log

Частые ошибки

  • После 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.

  • После правки .env приложение работает со старыми значениями, а env() вне файлов config/ возвращает null.

    Кэш конфига сбрасывают командой php artisan config:clear или пересобирают php artisan optimize. Значения из .env читайте только в файлах config/.

  • С opcache.validate_timestamps=0 новый код не подхватывается после деплоя, и на сайте остаётся старая версия.

    Перезагрузите PHP-FPM командой sudo systemctl reload php8.3-fpm. Проверьте конфиг FPM заранее через sudo php-fpm8.3 -t.

  • php artisan migrate на сервере с APP_ENV=production ждёт подтверждения и в неинтерактивном деплое зависает.

    Запускайте php artisan migrate --force. Флаг отключает вопрос и выполняет миграции сразу.

Deploykin

Как это делается в Deploykin

В Deploykin сайт на Laravel создаётся из панели: стек под приложение, key:generate и storage:link выполняются при создании, а доступы к базе сами попадают в .env. Деплой идёт без простоя, с миграциями и кэшами, а очереди держат демоны Horizon или Queue Worker.

7 дней бесплатно на тарифе Про, без привязки карты.

Вопросы и ответы

Какая версия PHP нужна для Laravel?

Laravel 13 требует PHP 8.3 и выше, и PHP 8.3 из Ubuntu 24.04 подходит. Laravel 11 и 12 тоже работают на PHP 8.3.

Чем Laravel отличается от чистого PHP?

Laravel даёт готовые маршруты, ORM Eloquent, шаблоны Blade, очереди и миграции. На чистом PHP каждую из этих частей пишут и поддерживают вручную.

Где Laravel пишет ошибки 500?

В storage/logs/laravel.log. При APP_DEBUG=false в браузере видна только общая страница, поэтому причину смотрят в логе.

Как проверить, что проект Laravel работает?

Откройте сайт в браузере и выполните curl -I http://example.com: должен прийти ответ 200. Список маршрутов покажет php artisan route:list.

Ещё по теме

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

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