К содержимому

Inertia Laravel: пошаговая настройка на Ubuntu 24.04

Inertia связывает Laravel и фронтенд на Vue, React или Svelte без API. На Ubuntu 24.04 с PHP 8.3 и Node.js 20+ это делается за несколько команд.

Руководство Laravel 2 мин чтения

01Проверьте окружение

Убедитесь, что в проекте Laravel 11 или новее и PHP 8.3. Node.js нужен версии 20 или выше: версия из репозитория Ubuntu 24.04 устарела для Vite. Проверьте версии командой php artisan --version и node -v.

bash
php artisan --version
node -v
npm -v

02Установите серверный адаптер Inertia

Пакет inertiajs/inertia-laravel добавляет middleware и хелпер inertia(). Он ставится через Composer в корне проекта. После установки создайте middleware командой php artisan inertia:middleware.

bash
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
<?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 набор пакетов будет другим, принцип тот же.

bash
npm install @inertiajs/vue3 vue @vitejs/plugin-vue --save-dev

05Настройте Vite

В vite.config.js подключите плагин Vue и укажите точку входа resources/js/app.js. Laravel-плагин уже добавлен в свежем проекте. Не меняйте имя точки входа без правки шаблона.

text
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 не смонтирует компонент.

text
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
<?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 не отдаёт тело.

bash
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: руководство по установке и настройке: все материалы темы

Мы используем cookies и сервис веб-аналитики «Яндекс Метрика» (включая Вебвизор) для улучшения работы сайта. Подробности — в политике конфиденциальности.