PHP Laravel: пошаговая настройка проекта на Ubuntu 24.04
Laravel это PHP-фреймворк для веб-приложений: маршруты, ORM Eloquent, шаблоны Blade и очереди в одном наборе пакетов. На Ubuntu 24.04 с PHP 8.3 проект создаётся одной командой Composer и запускается через встроенный сервер или nginx.
01Проверьте PHP и Composer
Laravel 13 требует PHP 8.3 и выше, а Ubuntu 24.04 ставит именно PHP 8.3. Убедитесь, что установлены CLI, FPM и расширения, без которых Composer и Laravel не работают. Если пакетов нет, поставьте их одной командой apt.
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.
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.
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.
php artisan migrate --force
05Настройте nginx на каталог public
Для Laravel root в nginx смотрит в /var/www/example.com/public, тогда .env и код вне public не отдаются наружу. Все запросы, которых нет среди файлов, передаются в index.php. После правки проверьте конфиг и перезагрузите 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.
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.
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 и права на файлы.
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 Filament в Laravel: установка и настройка панели Установка Filament 5 в Laravel на Ubuntu 24.04: панель /admin, пользователь, ресурс Customer, доступ на сервере и проверка входа без ошибки 403.
- Руководство · Laravel Laravel Livewire: установка и первый компонент на Ubuntu 24.04 Установка Livewire 4 в Laravel на Ubuntu 24.04: создание компонента, вывод на страницу, настройка nginx для livewire.min.js и проверка работы в браузере.
- Руководство · Laravel Laravel API: пошаговая настройка на Ubuntu 24.04 Как поднять API в Laravel на Ubuntu 24.04: установка Sanctum, маршруты в routes/api.php, проверка через curl, ответы 401 и 404, кэш и деплой.
- Руководство · Laravel Laravel Eloquent: настройка и проверка на Ubuntu 24.04 Пошаговая настройка Eloquent в Laravel на Ubuntu 24.04: подключение MySQL, миграции, модели, связи, проверка через tinker и маршрут.
- Руководство · Laravel Laravel install: установка фреймворка на Ubuntu 24.04 Пошаговая установка Laravel на Ubuntu 24.04: проверка PHP 8.3, composer create-project, ключ приложения,.env, миграции и запуск через php artisan serve.
- Руководство · Laravel Inertia Laravel: пошаговая настройка на Ubuntu 24.04 Подключите Inertia к Laravel на Ubuntu 24.04: установка пакетов, настройка Vite, создание страницы и проверка через curl и браузер.
Laravel: руководство по установке и настройке: все материалы темы