用 Inertia.js 建構 SPA

什麼是 Inertia.js

想用 React 或 Vue 寫前端，但又不想額外設計、實作、維護 API——解決這個兩難的正是 Inertia.js。 Inertia 是一種「膠水」，讓伺服器端的路由與 Controller 維持不變，只用 React、Vue、Svelte 撰寫前端。它不是框架，而是連接既有 Laravel 與 JavaScript 框架的介接層。

目前最新版本為 Inertia v3（2026 年 3 月 26 日發佈）。Laravel 13 的啟動套件（React、Vue、Svelte）皆已支援 Inertia。

與傳統 SPA、MPA 的差異

架構	特徵	課題
MPA（傳統 Blade 應用）	簡單，容易與 Laravel 整合	每次頁面切換都要 full reload
SPA（API + 前端分離）	互動性高	API 設計、認證、型別定義的雙重維護
Inertia（Modern Monolith）	SPA 的 UX + 伺服器端的簡潔	有其獨自的學習成本

使用 Inertia 可以從 Laravel Controller 直接把資料傳給 Vue 或 React 元件。不需要定義 REST API，頁面切換也不是全頁重新載入，而是透過 XHR 進行，因此能實現 SPA 般的流暢操作體驗。

與 Laravel 啟動套件的關係

使用 laravel new 建立專案時選擇 React、Vue、Svelte，會自動設置 Inertia。

laravel new my-app
# 於互動式 prompt 選 React / Vue / Svelte 時就會是 Inertia 架構

啟動套件會自動準備以下結構：

inertiajs/inertia-laravel（伺服器端 adapter）
@inertiajs/react / @inertiajs/vue3 / @inertiajs/svelte（用戶端 adapter）
HandleInertiaRequests middleware
登入、註冊、密碼重設等認證畫面（已用 Inertia 元件實作）

若要手動在既有專案導入 Inertia，需分別安裝伺服器端與用戶端。詳細請參考官方文件的安裝步驟。

`Inertia::render()` 基礎

要從 Laravel Controller 回傳 Inertia response，使用 Inertia::render()。第一參數是 JavaScript 元件名稱，第二參數是要當作 prop 傳入的資料。

use Inertia\Inertia;

class PostController extends Controller
{
    public function index()
    {
        return Inertia::render('Posts/Index', [
            'posts' => Post::latest()->paginate(10),
        ]);
    }

    public function show(Post $post)
    {
        return Inertia::render('Posts/Show', [
            'post' => $post->only('id', 'title', 'content', 'created_at'),
            'author' => $post->user->only('id', 'name'),
        ]);
    }
}

也可以使用 inertia() helper 函式代替 Inertia::render()。要用哪一種請團隊統一即可。

元件名稱 'Posts/Index' 對應到檔案路徑。React 則對應到 resources/js/Pages/Posts/Index.jsx；Vue 則對應到 resources/js/Pages/Posts/Index.vue。

頁面元件的結構

Inertia 的頁面元件就是一般的 Vue/React 元件。從 Controller 傳來的資料以 prop 接收。

React

// resources/js/Pages/Posts/Index.jsx
import { Link } from '@inertiajs/react'

export default function PostsIndex({ posts }) {
    return (
        <div>
            <h1>貼文列表</h1>
            {posts.data.map(post => (
                <article key={post.id}>
                    <h2>
                        <Link href={`/posts/${post.id}`}>{post.title}</Link>
                    </h2>
                </article>
            ))}
        </div>
    )
}

Vue

<!-- resources/js/Pages/Posts/Index.vue -->
<script setup>
import { Link } from '@inertiajs/vue3'

defineProps({
    posts: Object,
})
</script>

<template>
    <div>
        <h1>貼文列表</h1>
        <article v-for="post in posts.data" :key="post.id">
            <h2>
                <Link :href="`/posts/${post.id}`">{{ post.title }}</Link>
            </h2>
        </article>
    </div>
</template>

使用 <Link> 元件時，頁面切換會以 XHR 進行，可避免全頁重新載入。寫法與一般 <a> 標籤完全相同，但幕後由 Inertia 只替換頁面元件。

共用資料 — `HandleInertiaRequests` middleware

所有頁面都需要的共通資料（登入使用者資訊、flash 訊息等）可在 HandleInertiaRequests middleware 的 share() 方法中定義。

// app/Http/Middleware/HandleInertiaRequests.php
use Illuminate\Http\Request;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    public function share(Request $request): array
    {
        return array_merge(parent::share($request), [
            'appName' => config('app.name'),

            'auth' => [
                'user' => $request->user()
                    ? $request->user()->only('id', 'name', 'email')
                    : null,
            ],

            'flash' => [
                'success' => $request->session()->get('success'),
                'error' => $request->session()->get('error'),
            ],
        ]);
    }
}

共用資料會自動合併到所有頁面的 prop。

React

// 從 layout 元件存取的例子
import { usePage } from '@inertiajs/react'

export default function Layout({ children }) {
    const { auth, flash } = usePage().props

    return (
        <main>
            <header>
                {auth.user ? `登入中：${auth.user.name}` : '訪客'}
            </header>
            {flash.success && <div className="alert-success">{flash.success}</div>}
            <article>{children}</article>
        </main>
    )
}

共用資料會包含在每次請求裡，建議只放最必要的資料。使用 fn() 進行延遲求值，則只會在實際需要的請求中被求值。

表單送出與驗證錯誤處理

Inertia 的表單處理與 Laravel 驗證自然整合。使用 useForm() helper 可以簡潔地處理表單狀態、送出與錯誤顯示。

Controller 端

class PostController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            'title'   => ['required', 'string', 'max:255'],
            'content' => ['required', 'string'],
        ]);

        Post::create($validated + ['user_id' => auth()->id()]);

        return redirect()->route('posts.index')
            ->with('success', '貼文已建立。');
    }
}

發生驗證錯誤時，Laravel 會自動重新導向回表單頁面，並將錯誤存到 session。Inertia 會自動偵測並以 errors prop 傳給頁面。

前端

React

// resources/js/Pages/Posts/Create.jsx
import { useForm } from '@inertiajs/react'

export default function PostsCreate() {
    const { data, setData, post, processing, errors } = useForm({
        title: '',
        content: '',
    })

    function handleSubmit(e) {
        e.preventDefault()
        post('/posts')
    }

    return (
        <form onSubmit={handleSubmit}>
            <div>
                <label>標題</label>
                <input
                    value={data.title}
                    onChange={e => setData('title', e.target.value)}
                />
                {errors.title && <p className="error">{errors.title}</p>}
            </div>

            <div>
                <label>內容</label>
                <textarea
                    value={data.content}
                    onChange={e => setData('content', e.target.value)}
                />
                {errors.content && <p className="error">{errors.content}</p>}
            </div>

            <button type="submit" disabled={processing}>
                {processing ? '送出中...' : '發佈'}
            </button>
        </form>
    )
}

Vue

<!-- resources/js/Pages/Posts/Create.vue -->
<script setup>
import { useForm } from '@inertiajs/vue3'

const form = useForm({
    title: '',
    content: '',
})

function submit() {
    form.post('/posts')
}
</script>

<template>
    <form @submit.prevent="submit">
        <div>
            <label>標題</label>
            <input v-model="form.title" />
            <p v-if="form.errors.title" class="error">{{ form.errors.title }}</p>
        </div>

        <div>
            <label>內容</label>
            <textarea v-model="form.content"></textarea>
            <p v-if="form.errors.content" class="error">{{ form.errors.content }}</p>
        </div>

        <button type="submit" :disabled="form.processing">
            {{ form.processing ? '送出中...' : '發佈' }}
        </button>
    </form>
</template>

當驗證錯誤回來時，useForm() 會保留輸入內容並顯示錯誤，使用者不必重打，提升體驗。

適合與不適合的情境

Inertia 適合的情境

熟悉 Laravel 的團隊想做 SPA 般 UI
想在 Laravel 端集中處理認證、授權、驗證
管理介面、內部工具等 SEO 需求較低的應用
想避開額外設計、維護 API 成本的專案

不適合的情境

有多個外部用戶端（例如行動 App）共用同一 API
SEO 極為重要的內容型網站（雖可 SSR 但會變複雜）
微前端結構，前端由完全獨立的團隊開發時

Inertia 也支援伺服器端渲染（SSR）。若有 SEO 需求的頁面可考慮 SSR 選項。Laravel 啟動套件也內建了 SSR 設定。

Inertia v3 的主要變更

Inertia v3 於 2026 年 3 月 26 日發佈。以下介紹自 v2 的主要變更。

移除 Axios — 改為輕量內建 XHR client

v3 移除 Axios，改用更輕量的內建 XHR client。大多數應用不必修改程式碼。Axios interceptor 可直接改用內建 interceptor。若仍要使用 Axios，也可以透過 Axios adapter。

用 `@inertiajs/vite` plugin 簡化 SSR

導入新的 Vite plugin 後，頁面元件的自動解析與 SSR 設定大幅簡化。開發時 SSR 僅執行 npm run dev 即可運作，不再需要另開 Node server。

npm install @inertiajs/vite@^3.0

`useHttp` hook — 不帶頁面切換的 HTTP 請求

使用 useHttp hook 可以在不觸發頁面切換（Inertia visit）的情況下向伺服器送出 HTTP 請求。適合對話框儲存、背景處理等，希望維持目前頁面同時通訊的場景。

樂觀 UI 更新（Optimistic Updates）

useForm 與 router 層級皆支援樂觀更新。在未等伺服器回應下立即更新 UI，失敗時自動回滾。

Layout Props

使用 useLayoutProps hook 可以從頁面元件把資料傳給常駐 layout。原本只能靠共用資料或頁面 prop 處理的「特定頁面 layout 狀態控制」變得簡潔。

需求變更

v3 提升了以下最低版本要求。

項目	v2	v3
PHP	8.1+	8.2+
Laravel	10+	11+
React	18+	19+
Svelte	4+	5+

移除 `Inertia::lazy()`

v2 已棄用的 Inertia::lazy() 於 v3 完全移除。改用 Inertia::optional()。

// v2（已棄用）
'users' => Inertia::lazy(fn () => User::all()),

// v3
'users' => Inertia::optional(fn () => User::all()),

事件名稱變更

v2	v3
`invalid`	`httpException`
`exception`	`networkError`

移除 `future` 選項

v2 中作為實驗性選項提供的 future 設定區塊已被移除。這些選項皆已預設啟用。請從 createInertiaApp 設定中移除 future 區塊。

自 v2 升級的詳細步驟請參考官方升級指南。v2 的 bug 修正將提供至 2026 年 9 月 26 日，安全修正提供至 2027 年 3 月 26 日。

總結

Inertia.js 回應了「維持 Laravel 原貌但用 React/Vue 寫前端」這個現實需求的工具。最大優勢是不需設計 API，就能從 Controller 直接把資料傳給元件的簡潔性。從 Laravel 13 啟動套件對應 Inertia 也可看出，Inertia 在 Laravel 生態系中的定位已相當穩固。若說 Livewire 是「只用 PHP 就能做動態 UI」的路線，那 Inertia 則是「不損失伺服器端簡潔性，卻能發揮 JavaScript 框架威力」的路線。究竟該選哪一個取決於團隊技能與專案需求，但「維持 Laravel Controller 現狀，用 React 做畫面」的情境下，Inertia 是最自然的選擇。

Inertia.js 官方文件

Inertia v3 的完整功能請參考官方文件。

更新日誌

Laravel 13

產品

套件介紹

新版存放庫調查

升級指南

認證

前端

環境建置

什麼是 Inertia.js

與傳統 SPA、MPA 的差異

與 Laravel 啟動套件的關係

`Inertia::render()` 基礎

頁面元件的結構

共用資料 — `HandleInertiaRequests` middleware

表單送出與驗證錯誤處理

Controller 端

前端

適合與不適合的情境

Inertia 適合的情境

不適合的情境

Inertia v3 的主要變更

移除 Axios — 改為輕量內建 XHR client

用 `@inertiajs/vite` plugin 簡化 SSR

`useHttp` hook — 不帶頁面切換的 HTTP 請求

樂觀 UI 更新（Optimistic Updates）

Layout Props

需求變更

移除 `Inertia::lazy()`

事件名稱變更

移除 `future` 選項

總結

Inertia.js 官方文件

​什麼是 Inertia.js

​與傳統 SPA、MPA 的差異

​與 Laravel 啟動套件的關係

​Inertia::render() 基礎

​頁面元件的結構

​共用資料 — HandleInertiaRequests middleware

​表單送出與驗證錯誤處理

​Controller 端

​前端

​適合與不適合的情境

​Inertia 適合的情境

​不適合的情境

​Inertia v3 的主要變更

​移除 Axios — 改為輕量內建 XHR client

​用 @inertiajs/vite plugin 簡化 SSR

​useHttp hook — 不帶頁面切換的 HTTP 請求

​樂觀 UI 更新（Optimistic Updates）

​Layout Props

​需求變更

​移除 Inertia::lazy()

​事件名稱變更

​移除 future 選項

​總結

Inertia.js 官方文件

什麼是 Inertia.js

與傳統 SPA、MPA 的差異

與 Laravel 啟動套件的關係

`Inertia::render()` 基礎

頁面元件的結構

共用資料 — `HandleInertiaRequests` middleware

表單送出與驗證錯誤處理

Controller 端

前端

適合與不適合的情境

Inertia 適合的情境

不適合的情境

Inertia v3 的主要變更

移除 Axios — 改為輕量內建 XHR client

用 `@inertiajs/vite` plugin 簡化 SSR

`useHttp` hook — 不帶頁面切換的 HTTP 請求

樂觀 UI 更新（Optimistic Updates）

Layout Props

需求變更

移除 `Inertia::lazy()`

事件名稱變更

移除 `future` 選項

總結