Установка Laravel: что нужно проверить до первого запуска

К концу этой инструкции у вас в браузере откроется стартовая страница Laravel по адресу http://127.0.0.1:8000. На чистой машине с установленным PHP и Composer это займёт 15–20 минут: большую часть времени съедает не сам Laravel, а установка зависимостей и проверка версий. Ошибка чаще всего вылезает не на команде создания проекта, а раньше — из-за старого PHP или отсутствующего расширения. Поэтому начинаем с проверки окружения, а не со скачивания фреймворка.

Материал написан для Laravel 11.x (актуальная линейка на конец 2024 года). У Laravel 11 жёсткое требование: PHP 8.2 или новее. Если у вас PHP 8.1, Composer откажется ставить проект и напишет об этом прямо — угадывать не придётся.

Что нужно иметь до начала

Проверьте это до первой команды. Половина проблем новичков — не в Laravel, а в том, что чего-то из списка нет или версия старая.

• PHP 8.2+ — проверьте командой php -v. Первая строка покажет версию.
• Composer — менеджер зависимостей PHP¹. Проверьте: composer --version. Нужен Composer 2.x.
• Расширения PHP: OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath, Fileinfo. На большинстве сборок они включены по умолчанию, но на голом Linux часто не хватает mbstring и xml.
• База данных — не обязательна на старте. Laravel 11 по умолчанию настроен на SQLite, файл создаётся автоматически. MySQL или PostgreSQL подключите позже.

Как проверить набор расширений одной командой:

# Покажет все включённые расширения
php -m

# Проверить конкретное, например mbstring
php -m | grep mbstring

Если grep mbstring ничего не вывел — расширения нет, установите его через менеджер пакетов вашей системы (на Ubuntu это php8.2-mbstring) и повторите проверку.

Шаг 1. Создаём проект

Официальный способ для Laravel 11 — через Composer. Выполните в папке, где хотите держать проекты:

composer create-project laravel/laravel my-app

Здесь my-app — имя папки, которую Composer создаст и заполнит. Команда скачает фреймворк, поставит зависимости и сгенерирует ключ приложения. Процесс идёт минуту-две в зависимости от скорости сети.

Проверка: в конце в консоли появится сообщение вида Application key set successfully. и создастся папка my-app с файлами artisan, composer.json и каталогами app, routes, public.

Про глобальный установщик

Есть второй путь — установщик laravel new my-app. Он работает, если предварительно поставить пакет laravel/installer глобально через Composer. Для первого проекта этот шаг лишний: composer create-project не требует ничего ставить заранее и даёт тот же результат. Установщик удобнее, когда создаёте проекты часто.

Шаг 2. Проверяем конфигурацию

Composer автоматически скопировал .env.example в .env и сгенерировал ключ. Откройте .env и убедитесь, что строка APP_KEY= заполнена длинным значением с префиксом base64:. Если она пустая — сгенерируйте ключ вручную из папки проекта:

cd my-app
php artisan key:generate

Без заполненного APP_KEY приложение упадёт с ошибкой при попытке зашифровать сессию или cookie. Это одна из самых частых причин белого экрана у новичков.

Файл .env — единственное место с настройками окружения. Его не коммитят в Git, а .env.example коммитят как шаблон. Если склонировали чужой проект и получили ошибку про ключ — вы забыли скопировать .env и сгенерировать APP_KEY.

Шаг 3. Запускаем сервер разработки

Из папки проекта:

php artisan serve

Проверка: в консоли появится строка Server running on [http://127.0.0.1:8000]. Откройте этот адрес в браузере — увидите стартовую страницу Laravel с логотипом и ссылками на документацию. Сервер держится, пока открыто окно консоли; чтобы остановить, нажмите Ctrl+C.

Встроенный сервер artisan serve — только для разработки. Он однопоточный и не тянет реальную нагрузку. Для продакшена нужен Nginx или Apache с PHP-FPM, но это отдельная тема — на старте вам он не нужен.

Если не получилось

Типичные ошибки и что делать. Текст ошибки приведён так, как вы увидите его в консоли или браузере.

• «Your requirements could not be resolved ... requires php ^8.2» при create-project. У вас PHP старше 8.2. Проверьте php -v, обновите PHP или переключите версию, если их несколько.
• «the requested PHP extension mbstring is missing» (или ext-xml, ext-curl). Не хватает расширения — установите нужное и повторите команду.
• «No application encryption key has been specified» в браузере. Пустой APP_KEY — выполните php artisan key:generate.
• «Failed to listen on 127.0.0.1:8000 (reason: Address already in use)». Порт занят другим процессом. Запустите на другом порту: php artisan serve --port=8001.
• «could not find driver» при обращении к базе. Не хватает драйвера PDO для вашей СУБД — для SQLite это php8.2-sqlite3, для MySQL php8.2-mysql.

Права на папки — что часто ломается

На Linux и macOS Laravel пишет во время работы в две папки: storage и bootstrap/cache. Туда падают логи, кеш и скомпилированные шаблоны. Если веб-сервер не может в них писать, вы получите ошибку доступа. При запуске через artisan serve под своим пользователем проблема обычно не возникает, но проявляется при переносе на боевой сервер под другим пользователем.

Что делать дальше

Проект запустился — дальше по порядку:

• Подключите базу: правьте блок DB_* в .env, затем выполните php artisan migrate, чтобы создать таблицы из стандартных миграций.
• Разберитесь с маршрутами — файл routes/web.php. Стартовая страница описана именно там.
• Если нужен фронтенд-сборщик, Laravel 11 идёт с Vite; для него нужен Node.js, команды npm install и npm run dev.

Настройка боевого сервера, очереди, кеш Redis — отдельные темы. Здесь вы получили работающее локальное окружение, и этого достаточно, чтобы начать писать код.