PHP 怎么PHP Inertia

wen PHP项目 2026-08-01 2

本文目录导读：

PHP 怎么PHP Inertia

什么是 Inertia.js
安装步骤
基本使用
常用方法
高级功能
完整项目示例
注意事项

我来详细讲解 PHP 中如何使用 Inertia.js。

什么是 Inertia.js

Inertia.js 是一个用于构建单页应用（SPA）的库，它允许你使用服务端路由和控制器，同时提供 SPA 的用户体验，无需构建 API。

安装步骤

安装 Laravel 后端包

composer require inertiajs/inertia-laravel

安装前端依赖

npm install @inertiajs/inertia @inertiajs/inertia-vue3
# 或 React 版本
npm install @inertiajs/inertia @inertiajs/inertia-react

设置根模板

创建 resources/views/app.blade.php：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">My App</title>
    @vite
</head>
<body>
    @inertia
</body>
</html>

配置中间件

// app/Http/Middleware/HandleInertiaRequests.php
namespace App\Http\Middleware;
use Illuminate\Http\Request;
use Inertia\Middleware;
class HandleInertiaRequests extends Middleware
{
    public function share(Request $request)
    {
        return array_merge(parent::share($request), [
            'auth' => [
                'user' => $request->user(),
            ],
            'flash' => [
                'message' => session('message'),
            ],
        ]);
    }
}

基本使用

控制器返回 Inertia 响应

// app/Http/Controllers/UserController.php
use Inertia\Inertia;
class UserController extends Controller
{
    public function index()
    {
        $users = User::all();
        return Inertia::render('Users/Index', [
            'users' => $users
        ]);
    }
    public function show(User $user)
    {
        return Inertia::render('Users/Show', [
            'user' => $user
        ]);
    }
}

Vue 组件（以 Vue 3 为例）

<!-- resources/js/Pages/Users/Index.vue -->
<script setup>
import { Link } from '@inertiajs/inertia-vue3';
defineProps({
    users: Array
});
</script>
<template>
    <div>
        <h1>用户列表</h1>
        <div v-for="user in users" :key="user.id">
            <Link :href="`/users/${user.id}`">
                {{ user.name }}
            </Link>
        </div>
    </div>
</template>

常用方法

页面导航

<!-- 使用 Link 组件 -->
<script setup>
import { Link } from '@inertiajs/inertia-vue3';
</script>
<template>
    <Link href="/users" class="nav-link">
        用户列表
    </Link>
</template>

程序化导航

import { router } from '@inertiajs/inertia';
// 导航到新页面
router.visit('/users');
// 带参数
router.visit('/users', {
    method: 'post',
    data: {
        name: 'John Doe'
    }
});
// 带查询参数
router.get('/users', { search: 'john' });

表单处理

<script setup>
import { useForm } from '@inertiajs/inertia-vue3';
const form = useForm({
    name: '',
    email: '',
});
function submit() {
    form.post('/users', {
        onSuccess: () => form.reset(),
    });
}
</script>
<template>
    <form @submit.prevent="submit">
        <input v-model="form.name" type="text">
        <div v-if="form.errors.name">{{ form.errors.name }}</div>
        <input v-model="form.email" type="email">
        <div v-if="form.errors.email">{{ form.errors.email }}</div>
        <button type="submit" :disabled="form.processing">
            提交
        </button>
    </form>
</template>

高级功能

局部加载

<script setup>
import { router } from '@inertiajs/inertia';
// 只更新特定组件的数据
router.visit('/users', {
    only: ['users'],
    preserveState: true
});
</script>

延迟加载（懒加载）

<!-- resources/js/Pages/Users/Index.vue -->
<script setup>
import { defineAsyncComponent } from 'vue';
import { Head } from '@inertiajs/inertia-vue3';
const UserProfile = defineAsyncComponent(() => import('./UserProfile'));
defineProps({
    users: Array,
    showProfile: Boolean
});
</script>
<template>
    <Head title="Users" />
    <UserProfile v-if="showProfile" />
</template>

共享数据

// 在中间件中共享数据
public function share(Request $request)
{
    return array_merge(parent::share($request), [
        'app' => [
            'name' => config('app.name'),
            'version' => '1.0.0'
        ],
        'user' => $request->user() ? [
            'id' => $request->user()->id,
            'name' => $request->user()->name,
            'email' => $request->user()->email,
        ] : null,
    ]);
}

响应修饰符

// 设置状态码
return Inertia::render('Users/Show', [
    'user' => $user
])->with('status', 200);
// 设置自定义标题
return Inertia::render('Users/Show', [
    'user' => $user
])->withViewData(['meta' => ['title' => '用户详情']]);

完整项目示例

// routes/web.php
Route::middleware(['auth'])->group(function () {
    Route::get('/', [DashboardController::class, 'index']);
    Route::resource('users', UserController::class);
    Route::resource('posts', PostController::class);
});

// resources/js/app.js
import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/inertia-vue3';
import { resolvePageComponent } from 'vite-plugin-laravel/inertia';
createInertiaApp({
    resolve: (name) => resolvePageComponent(
        `./Pages/${name}.vue`,
        import.meta.glob('./Pages/**/*.vue')
    ),
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) })
            .use(plugin)
            .mount(el);
    },
});

注意事项

版本兼容性：确保 Laravel 和前端库版本兼容
Vite 配置：确保正确配置 Vite 来处理 Vue/React 文件
CSRF 令牌：处理 POST 请求时需要 CSRF 保护
缓存策略：合理使用缓存来提高性能
错误处理：实现全局错误处理

这只是一个基础教程，Inertia.js 还提供了很多高级功能，如服务器端渲染、延迟加载组件、自定义历史管理等,建议查阅官方文档获取更详细的信息。