Установка Laravel: частые ошибки новичков и как их обойти

За полчаса вы получите чистый проект Laravel 11, который открывается в браузере и не падает при первом же запросе. Ниже — точная последовательность команд и разбор пяти ошибок, на которые новичок натыкается в первый день: белый экран без объяснений, No application encryption key, отказ в правах на папку storage и падение при обращении к базе. Речь про Laravel 11.x и PHP 8.2+ — минимальную версию, которую требует эта ветка фреймворка.

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

Laravel ставится через Composer, а не скачивается архивом. Проверьте, что на машине есть всё из списка, иначе установка оборвётся на середине.

• PHP 8.2 или новее. Проверка: php -v. Laravel 11 не запустится на PHP 8.1 — это жёсткое требование, а не рекомендация.
• Composer. Проверка: composer --version. Если команда не найдена — Composer не установлен или не добавлен в PATH.
• Расширения PHP: mbstring, openssl, pdo, tokenizer, xml, ctype, json, bcmath, fileinfo, curl. Список включённых расширений покажет php -m.
• База данных — если проект будет с ней работать. Для старта хватит SQLite (файл, ничего ставить не надо) или MySQL/PostgreSQL, если он уже поднят.

Отдельная частая засада: на Windows расширения включаются в php.ini, и по умолчанию многие закомментированы точкой с запятой. Если php -m не показывает openssl или pdo_mysql — найдите соответствующую строку ;extension=... в php.ini, уберите точку с запятой и перезапустите терминал.

Laravel — это не файлы, которые кладут в папку хостинга. Это зависимости, которые собирает Composer. Пока вы думаете о нём как о готовом архиве, половина ошибок будет казаться необъяснимой.

Шаги установки

1. Создайте проект командой Composer. В папке, где хотите держать проекты, выполните:

   composer create-project laravel/laravel my-app

   Composer скачает фреймворк и все зависимости в папку my-app. Это займёт от одной до нескольких минут — зависит от скорости сети. Проверка: в конце в терминале появится строка вроде Application ready! Build something amazing., а внутри my-app будут папки app, routes, config.

2. Перейдите в папку проекта:

   cd my-app

3. Проверьте, что появился файл .env и в нём есть APP_KEY. create-project обычно копирует .env.example в .env и генерирует ключ автоматически. Если ключа нет — выполните:

   php artisan key:generate

   Проверка: откройте .env, строка APP_KEY= должна заканчиваться длинным значением с префиксом base64:.

4. Запустите встроенный сервер разработки:

   php artisan serve

   Проверка: в терминале появится Server running on [http://127.0.0.1:8000]. Откройте этот адрес в браузере — увидите стартовую страницу Laravel.

На этом рабочий проект уже запущен. Сервер artisan serve — только для разработки; в продакшене его не используют, там ставят Nginx или Apache с указанием на папку public.

Про базу данных: SQLite за минуту

Если база нужна прямо сейчас, а MySQL поднимать лень, откройте .env и приведите блок к SQLite:

DB_CONNECTION=sqlite
# остальные DB_* строки для SQLite можно закомментировать или удалить

Затем создайте файл базы и прогоните миграции:

php artisan migrate

В свежих версиях Laravel 11 при использовании SQLite файл database/database.sqlite создаётся автоматически, но если миграция жалуется на отсутствие файла — создайте пустой файл вручную по этому пути и повторите команду. Проверка: команда выведет список применённых миграций со статусом DONE.

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

Пять ошибок, которые ловят почти все на первом проекте — с текстом, который вы реально увидите.

1. Белый экран или ошибка 500 без объяснений

Открыли 127.0.0.1:8000 — пусто или голая ошибка сервера. Первое, что нужно сделать, — увидеть текст ошибки. Убедитесь, что в .env стоит:

APP_DEBUG=true

Тогда вместо белого экрана появится подробная страница с трейсом. Если и после этого пусто — смотрите логи в storage/logs/laravel.log, там причина будет написана прямым текстом. Важно: APP_DEBUG=true оставляют только на локальной машине. На боевом сервере это раскрывает пути, переменные окружения и куски кода посторонним.

2. No application encryption key has been specified

Ошибка означает, что APP_KEY в .env пустой. Лечится одной командой:

php artisan key:generate

Если после этого ничего не изменилось — сбросьте кеш конфигурации: php artisan config:clear. Laravel мог закешировать пустое значение.

3. The stream or file storage/logs/laravel.log could not be opened

Или похожее про Permission denied на storage и bootstrap/cache. Веб-серверу или PHP не хватает прав на запись в эти папки. На Linux/macOS дайте права:

chmod -R 775 storage bootstrap/cache

Если сайт крутится под отдельным пользователем веб-сервера (например, www-data), может понадобиться сменить владельца этих папок на него — точную команду и имя пользователя сверьте с настройками вашего сервера. При запуске через artisan serve под своим пользователем проблема с правами обычно не возникает вовсе.

4. SQLSTATE[HY000] [2002] Connection refused

Laravel пытается достучаться до базы, а её нет или данные подключения неверны. Проверьте в .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=имя_базы
DB_USERNAME=пользователь
DB_PASSWORD=пароль

Частые причины: сервер MySQL не запущен, база с таким именем ещё не создана (Laravel сам её не создаёт — только таблицы), или в DB_HOST стоит localhost там, где нужен 127.0.0.1 (на некоторых конфигурациях это разные пути подключения). После правки .env выполните php artisan config:clear.

5. Изменил .env, а ничего не поменялось

Классика: правите .env, перезагружаете страницу — старое поведение. Причина — закешированная конфигурация. Сбросьте кеш:

php artisan config:clear

Если запускали php artisan config:cache раньше (это делают на проде для скорости) — на этапе разработки от него лучше отказаться, иначе каждое изменение .env придётся пересобирать вручную.

Таблица: что куда вписать в .env для старта

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

Проект запущен — теперь имеет смысл разобраться с тремя вещами по порядку: как работают маршруты в routes/web.php, как устроены миграции и модели, и как отдаётся вёрстка через Blade. Если планируете фронтенд-сборку (Tailwind, Vite) — в свежем Laravel Vite уже подключён, команда npm install и npm run dev поднимут сборку ассетов, для этого понадобится Node.js. Перед выкладкой на боевой сервер обязательно переключите APP_DEBUG на false и настройте веб-сервер на папку public, а не на корень проекта.