Laravel API: пошаговая настройка на Ubuntu 24.04
В свежем проекте Laravel файла routes/api.php нет, поэтому API начинается с команды php artisan install:api. Она ставит Laravel Sanctum и подключает маршруты API в bootstrap/app.php. Дальше вы опишете маршруты, проверите ответы через curl и подготовите проект к работе на сервере.
01Проверьте окружение
Зайдите на сервер под пользователем, который деплоит проект, и убедитесь, что установлены PHP 8.3, Composer и расширения, нужные Laravel: php8.3-mbstring, php8.3-xml, php8.3-curl, php8.3-zip, php8.3-bcmath, php8.3-intl и php8.3-mysql. Laravel 13 требует PHP 8.3 и выше, PHP 8.3 из Ubuntu 24.04 подходит. Если PHP или Composer не установлены, их ставят пакетами Ubuntu, а установка самого Laravel разобрана на отдельной странице.
php -v
composer --version
php -m | grep -E 'mbstring|xml|curl|zip|bcmath|intl|pdo_mysql'
02Создайте проект и проверьте версию
Создайте проект в каталоге /var/www/example.com командой composer create-project. Версию фреймворка показывает php artisan --version. В свежем проекте база по умолчанию sqlite, а очереди и кэш пишутся в базу. Для MySQL поменяйте в.env значения DB_CONNECTION, DB_HOST, DB_DATABASE, DB_USERNAME и DB_PASSWORD и создайте пустую базу.
cd /var/www
composer create-project laravel/laravel example.com
cd example.com
php artisan --version
03Создайте ключ приложения и таблицы
Ключ шифрования создают один раз командой php artisan key:generate: без него Laravel отвечает ошибкой No application encryption key has been specified. Затем примените миграции. В Laravel 11 и новее драйвер сессий по умолчанию database, поэтому таблица sessions из миграций нужна и для API-проекта.
php artisan key:generate
php artisan migrate
04Установите Sanctum и подключите маршруты API
Команда php artisan install:api ставит Laravel Sanctum 4, создаёт файл routes/api.php и подключает его в bootstrap/app.php. Отдельно ставить пакет не нужно. После команды маршруты API доступны по префиксу /api.
php artisan install:api
05Опишите маршруты в routes/api.php
Маршруты API пишут в routes/api.php, к ним автоматически добавляется префикс /api. Публичный маршрут объявляют через Route::get, защищённый закрывают middleware auth:sanctum. Для проверки добавьте маршрут, который возвращает JSON, и защищённый маршрут, который отдаёт имя пользователя.
<?php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::get('/ping', function () {
return response()->json(['status' => 'ok']);
});
Route::get('/user', function (Request $request) {
return $request->user();
})->middleware('auth:sanctum');
06Посмотрите список маршрутов
Команда php artisan route:list показывает все маршруты с методами, адресами и middleware. В выводе найдите /api/ping и /api/user и убедитесь, что у второго стоит auth:sanctum. Если маршрутов API в списке нет, проверьте, что routes/api.php подключён в bootstrap/app.php.
php artisan route:list
07Проверьте ответы через curl
Запустите встроенный сервер командой php artisan serve и отправьте два запроса. Публичный маршрут вернёт JSON со статусом ok. Запрос к защищённому маршруту без токена и с заголовком Accept: application/json получит ответ 401: именно при этом заголовке Laravel отвечает кодом, а без него пытается перенаправить на маршрут login и падает с ошибкой Route [login] not defined.
php artisan serve --host=127.0.0.1 --port=8000
curl -i http://127.0.0.1:8000/api/ping
curl -i -H 'Accept: application/json' http://127.0.0.1:8000/api/user
08Настройте nginx на каталог public
Для Laravel root в nginx смотрит в /var/www/example.com/public, чтобы.env и код вне public не отдавались наружу. Запросы, которых нет на диске, передаются в index.php. Если в конфиге есть отдельный location для файлов.js с try_files $uri =404,, скрипт Livewire по адресу /livewire-<хеш>/livewire.min.js получит 404, поэтому такие запросы тоже отправляйте в index.php.
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;
}
}
Частые ошибки
-
Клиент API получает редирект на /login и ошибку Route [login] not defined.
Добавьте в запрос заголовок Accept: application/json, тогда Laravel вернёт 401 вместо перенаправления.
-
После php artisan optimize правка.env не действует, а env() вне config/ возвращает null.
Читайте настройки через config() и после правки.env запускайте php artisan optimize или php artisan config:clear.
-
Запрос к /api/ping возвращает 404.
Проверьте, что выполнен php artisan install:api и routes/api.php подключён в bootstrap/app.php, затем посмотрите вывод php artisan route:list.
-
В браузере ошибка No application encryption key has been specified.
Выполните php artisan key:generate, а при закэшированном конфиге затем php artisan config:cache.
Deploykin
Как это делается в Deploykin
В Deploykin сайт на Laravel создаётся из панели: стек под приложение, key:generate и storage:link выполняются при создании, а доступы к базе сами попадают в .env. Деплой идёт без простоя, с миграциями и кэшами, а очереди держат демоны Horizon или Queue Worker.
7 дней бесплатно на тарифе Про, без привязки карты.
Вопросы и ответы
Почему в Laravel нет файла routes/api.php?
В Laravel 11 и новее его не создают при установке. Файл и маршруты API подключает команда php artisan install:api, она же ставит Laravel Sanctum.
Как защитить маршрут API токеном?
Закройте маршрут middleware auth:sanctum. Клиент передаёт токен в заголовке Authorization: Bearer <токен>.
Почему API отвечает 401 вместо JSON с ошибкой входа?
Laravel отвечает 401, когда клиент прислал Accept: application/json. Без этого заголовка он пытается перенаправить на маршрут login.
Что делать после изменения.env на сервере?
Выполните php artisan optimize или php artisan config:clear. При закэшированном конфиге env() вне файлов config/ возвращает null, а старые значения остаются в кэше.
Ещё по теме
- Руководство · Laravel PHP Laravel: пошаговая настройка проекта на Ubuntu 24.04 Создайте проект Laravel на PHP 8.3 в Ubuntu 24.04: Composer,.env, MySQL, миграции, nginx, кэш и проверка запуска. Команды и типичные ошибки.
- Руководство · 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 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: руководство по установке и настройке: все материалы темы