Inertia::render() 返回空白页或404，根本原因是链路中断：中间件未注册（Kernel.php中web组缺\Inertia\Middleware::class）、路由未走web组、app.blade.php缺@inertia指令、前端resolve路径与组件名不匹配或Vue3未用defineProps声明props。
Inertia::render() 返回空白页或 404，基本就是中间件没挂上、前端没加载、或组件路径对不上——不是代码写错了，是链路断在了中间。
为什么 Inertia::render() 不生效，页面还是白的
最常踩的坑是以为装了包就自动生效。实际上 Inertia 完全依赖中间件注入响应逻辑，不手动注册就等于没接通。
-
app/Http/Kernel.php的$middlewareGroups['web']必须包含\Inertia\Middleware::class（Laravel 10+ 默认已存在，但老项目或自定义 Kernel 可能漏掉） - 路由必须走
web中间件组：用Route::get('/', ...)没问题，但若显式写了->middleware('api')或没指定中间件组，Inertia::render()就会退化成普通响应，返回空内容 -
resources/views/app.blade.php里必须有@inertia指令（不是<div id="app"></div>加 script 就够），它负责注入初始 props 和容器 DOM 结构 - 前端
createInertiaApp()的resolve函数路径要严格匹配控制器传入的组件名，比如Inertia::render('User/Profile')对应./Pages/User/Profile.vue，少个斜杠或大小写错都 404
Vue 3 组件怎么拿到 Laravel 传来的数据
不是 axios.get() 拉，也不是 this.$page.props 手动取——Inertia 把数据当 props 直接“塞”进组件实例，Vue 3 要显式声明才能解构。
- 控制器里传数据：
return Inertia::render('Dashboard', ['stats' => $stats, 'user' => auth()->user()]); - Vue 3
<script setup></script>中必须用defineProps()声明类型：defineProps({ stats: Object, user: Object });；不声明也能用，但控制台会报 runtime warning，且 TypeScript 下直接报错 - 敏感字段如
password_hash、remember_token别往 props 里塞，Inertia::render()传输无加密，数据在 HTML 源码里明文可见 - 想在组件里访问全局状态（比如当前用户），优先用
usePage().props.auth.user，而不是重复传参，避免冗余和不一致
表单提交后页面跳转失败，还刷了整页
原生 <form></form> 提交默认触发浏览器全量刷新，Inertia 不会自动拦截——必须显式调用 Inertia 方法，且后端不能用 redirect()。
- 前端用
useForm()：const form = useForm({ email: '', password: '' }); form.post('/login'); - 后端控制器处理成功后，不要 写
return redirect()->route('dashboard');，而要直接return Inertia::render('Dashboard');；Inertia 会把 302 当作普通响应忽略，只认Inertia::render()返回的页面结构 - 如果需要重定向并保持滚动位置（比如聊天框发消息后回到 /home），前端
post()必须设preserveState: false，后端必须用redirect()->route('home')（命名路由），不能用字符串路径如redirect('index/home')
前端入口没挂载但控制台不报错
Vue 3 使用 createApp()，不能混用 Vue 2 的 new Vue() 写法，否则挂载失败但控制台无报错——页面就白着。
- 检查
resources/js/app.js是否调用createInertiaApp()并正确传入resolve函数 -
resolve返回的组件必须是可执行的模块，常见错误包括：路径拼错、.vue文件导出语法不对（Vue 3 要export default { ... }或<script setup></script>）、文件未被 Vite/Webpack 解析 - Vite 项目中确保
vite.config.js启用了对应插件（@vitejs/plugin-vue或@vitejs/plugin-react），否则.vue文件不会被编译
真正卡住的地方往往不在代码逻辑本身，而在中间件注册顺序、路由中间件组归属、@inertia 指令是否真的出现在最终渲染的 HTML 里——这些地方没有报错提示，但一断就整个链路失效。
