Inertia Laravel: пошаговая настройка на Ubuntu 24.04
Inertia связывает Laravel и фронтенд на Vue, React или Svelte без API. На Ubuntu 24.04 с PHP 8.3 и Node.js 20+ это делается за несколько команд.
01Проверьте окружение
Убедитесь, что в проекте Laravel 11 или новее и PHP 8.3. Node.js нужен версии 20 или выше: версия из репозитория Ubuntu 24.04 устарела для Vite. Проверьте версии командой php artisan --version и node -v.
php artisan --version
node -v
npm -v
02Установите серверный адаптер Inertia
Пакет inertiajs/inertia-laravel добавляет middleware и хелпер inertia(). Он ставится через Composer в корне проекта. После установки создайте middleware командой php artisan inertia:middleware.
composer require inertiajs/inertia-laravel
php artisan inertia:middleware
03Подключите middleware в bootstrap/app.php
В Laravel 11 и новее middleware регистрируют в bootstrap/app.php. Добавьте HandleInertiaRequests в группу web, чтобы он видел сессию и CSRF-токен. Файла app/Http/Kernel.php в этих версиях нет.
<?php
use Illuminate\Foundation\Configuration\Middleware;
use App\Http\Middleware\HandleInertiaRequests;
return Application::configure(basePath: dirname(__DIR__))
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
HandleInertiaRequests::class,
]);
})
->create();
04Установите клиентский адаптер и Vite-плагин
Для Vue 3 нужны пакеты @inertiajs/vue3 и @vitejs/plugin-vue. Они ставятся в dev-зависимости, потому что нужны только при сборке. Для React или Svelte набор пакетов будет другим, принцип тот же.
npm install @inertiajs/vue3 vue @vitejs/plugin-vue --save-dev
05Настройте Vite
В vite.config.js подключите плагин Vue и укажите точку входа resources/js/app.js. Laravel-плагин уже добавлен в свежем проекте. Не меняйте имя точки входа без правки шаблона.
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
plugins: [
laravel({
input: 'resources/js/app.js',
}),
vue(),
],
});
06Создайте точку входа и корневой шаблон
В resources/js/app.js создайте приложение Vue и подключите плагин Inertia. В resources/views/app.blade.php оставьте <div id="app" data-page="{...}"> и подключите @vite и @inertiaHead. Без data-page Inertia не смонтирует компонент.
import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
createInertiaApp({
resolve: name => import(`./Pages/${name}.vue`),
setup({ el, App, props, plugin }) {
createApp({ render: () => h(App, props) })
.use(plugin)
.mount(el);
},
});
07Создайте страницу и маршрут
Положите компонент resources/js/Pages/Home.vue. В routes/web.php верните его через Inertia::render. Имя компонента должно совпадать с путём в resolve.
<?php
use Inertia\Inertia;
use Illuminate\Support\Facades\Route;
Route::get('/', function () {
return Inertia::render('Home', [
'message' => 'Inertia работает',
]);
});
08Соберите фронтенд и проверьте результат
Запустите npm run build, затем откройте сайт в браузере. В исходном HTML должен быть <div id="app" data-page="..."> с JSON-данными страницы. Проверьте ответ через curl без флага -I, потому что HEAD не отдаёт тело.
npm run build
curl -s http://example.com/ | grep -o 'data-page="[^"]*"'
Частые ошибки
-
Node.js 18 из репозитория Ubuntu 24.04 не подходит для Vite 5 и новее, сборка падает с ошибкой о версии.
Поставьте Node.js 20 или 22 из NodeSource или через nvm, затем пересоберите
npm run build. -
После
php artisan optimizeна сервере старые файлы изpublic/buildостаются, и браузер грузит прежний JS.php artisan optimizeкэширует конфиг, маршруты, события и шаблоны, но не собирает фронтенд. Ассеты обновляет толькоnpm run build. -
Проверка через
curl -I http://example.com/не показывает<div id="app" data-page="...">, и кажется, что Inertia не подключилась.curl -Iотправляет HEAD и возвращает только заголовки. Для проверки HTML используйтеcurl http://example.com/без-I. -
Middleware
HandleInertiaRequestsне зарегистрирован, и ответ приходит без заголовкаX-Inertia.Добавьте его в группу
webвbootstrap/app.phpи очистите кэш конфига командойphp artisan config:clear.
Deploykin
Как это делается в Deploykin
В Deploykin сайт на Laravel создаётся из панели: стек под приложение, key:generate и storage:link выполняются при создании, а доступы к базе сами попадают в .env. Деплой идёт без простоя, с миграциями и кэшами, а очереди держат демоны Horizon или Queue Worker.
7 дней бесплатно на тарифе Про, без привязки карты.
Вопросы и ответы
Нужен ли API-маршрут для Inertia?
Нет. Inertia передаёт данные через обычные веб-маршруты Laravel и не требует routes/api.php.
Можно ли использовать Inertia с React вместо Vue?
Да. Установите @inertiajs/react и @vitejs/plugin-react, а в app.js замените createInertiaApp на версию для React.
Почему после деплоя страница пустая?
Проверьте, что выполнен npm run build и в шаблоне подключён @vite. Если ассеты собраны, но не видны, очистите кэш шаблонов командой php artisan view:clear.
Как проверить, что Inertia отвечает JSON при навигации?
Отправьте запрос с заголовком X-Inertia: true и X-Inertia-Version из ответа. Сервер вернёт JSON с полями component, props и url.
Ещё по теме
- Руководство · 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 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: руководство по установке и настройке: все материалы темы