Inertia.js+Laravel移动端显示空白页问题求助

针对PC端及局域网访问正常、移动端页面仅加载app.blade.php但React组件未渲染的问题，可按以下步骤排查：

1. 检查Vite资源路径配置 #

移动端访问失败常因资源路径不匹配导致：

• 确认.env文件中APP_URL设置为移动端可访问的地址（如局域网IP或公网域名），而非localhost。
• 修改vite.config.js，确保允许外部访问并配置正确的构建路径：

export default defineConfig({
  plugins: [
    laravel({
      input: 'resources/js/app.jsx',
      refresh: true,
    }),
    react(),
  ],
  server: {
    host: '0.0.0.0', // 允许局域网/外部设备访问
    port: 5173,
  },
  build: {
    outDir: 'public/build',
    assetsDir: 'assets',
  },
})

• 重新执行npm run build，并清理移动端浏览器缓存后测试。

2. 排查Inertia初始化与CSRF令牌问题 #

移动端可能存在CSRF验证失败或Inertia初始化错误：

• 打开移动端浏览器控制台（如Firefox Nightly DevTools），查看是否有JS报错（如CSRF令牌不匹配、Inertia初始化失败）。
• 确认app.blade.php中的csrf-token meta标签正常输出，移动端请求是否携带X-CSRF-TOKEN请求头。
• 检查resources/js/app.jsx中的Inertia初始化代码是否正确：

import { createInertiaApp } from '@inertiajs/react';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
import { createRoot } from 'react-dom/client';

createInertiaApp({
  resolve: (name) => resolvePageComponent(`./Pages/${name}.jsx`, import.meta.glob('./Pages/**/*.jsx')),
  setup({ el, App, props }) {
    createRoot(el).render(<App {...props} />);
  },
});

3. 验证移动端浏览器兼容性 #

部分移动端浏览器对ES6+语法支持不足：

• 在vite.config.js中指定构建目标为兼容更多浏览器：

export default defineConfig({
  // ...其他配置
  build: {
    target: 'es2015',
  },
})

• 临时移除第三方组件（如Font Awesome、自定义UI组件），测试移动端是否能正常渲染，排查兼容性问题。

4. 捕获页面组件渲染错误 #

可能是某个React组件在移动端抛出错误导致页面空白：

• 在app.jsx中添加错误捕获，定位出错组件：

createInertiaApp({
  resolve: (name) => resolvePageComponent(`./Pages/${name}.jsx`, import.meta.glob('./Pages/**/*.jsx')),
  setup({ el, App, props }) {
    try {
      createRoot(el).render(<App {...props} />);
    } catch (error) {
      console.error('页面渲染错误:', error);
    }
  },
});

• 替换为极简测试组件（如下），验证基础渲染是否正常：

// resources/js/Pages/Test.jsx
export default function Test() {
  return <div>移动端测试页面</div>;
}

将路由指向该组件，测试移动端访问情况。

5. 清理缓存 #

移动端浏览器或Laravel缓存可能导致旧资源残留：

• 执行php artisan optimize:clear清理Laravel路由、视图、配置缓存。
• 移动端浏览器强制刷新页面（长按刷新按钮选择“强制刷新”），或直接清除浏览器缓存。

附用户提供的app.blade.php代码 #

<!DOCTYPE html>
<html lang="{{ auth()->check() ? json_decode(auth()->user()->settings)->lang : "en"}}" class={{ auth()->check() ? json_decode(auth()->user()->settings)->theme : "dark"}}>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">

        <title inertia>{{ env('APP_NAME', 'Laravel') }}</title>
        <meta name="csrf-token" content="{{ csrf_token() }}">
        <!-- Fonts -->
        <link rel="preconnect" href="https://fonts.googleapis.com">
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700&display=swap" rel="stylesheet">
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" integrity="sha512-DTOQO9RWCH3ppGqcWaEA1BIZOC6xxalwEsw9c2QQeAIftl+Vegovlnee1c9QX4TctnWMn13TZye+giMm8e2LwA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
        <!-- Scripts -->
        @routes
        @viteReactRefresh
        @vite(['resources/js/app.jsx', "resources/js/Pages/{$page['component']}.jsx"])
        @inertiaHead
    </head>
    <body class="font-sans antialiased bg-neutral-200 dark:bg-slate-900">
        @inertia
    </body>
</html>

内容的提问来源于stack exchange，提问作者Speed