Laravel InertiaJS SSR返回无.tsx内容的app.blade.php引发Hydration失败

问题描述 #

• SSR 返回的 app.blade.php 不包含 .tsx 页面内容
• 客户端渲染触发 Hydration failed because the server rendered HTML didn't match the client 错误
• 所有构建、服务启动命令（npm run build/npm run dev/php artisan inertia:start-ssr/php artisan serve）无异常日志
• 已在 inertia.php 中启用 SSR 配置，但访问 http://127.0.0.1:13714 返回 NOT_FOUND 状态
• 使用 Laravel 12 官方启动套件（带 React + SSR 选项）

排查修复步骤 #

1. 解决 SSR 服务 404 问题 #

访问 SSR 服务地址返回 404，说明服务未正确处理请求：

• 确认 ssr.tsx 中页面路径与实际文件匹配：控制器返回 Inertia::render('home')，需保证 pages/home.tsx 文件名、目录结构完全对应
• 检查 SSR 服务启动状态：执行 php artisan inertia:start-ssr 后，终端需显示 SSR server started on http://127.0.0.1:13714，无此提示则需检查依赖或编译问题

2. 修复 Hydration 不匹配错误 #

当前 app.tsx 未区分 SSR/非 SSR 场景，强制使用 hydrateRoot 导致不匹配，修改代码：

setup({ el, App, props }) {
  if (el.hasAttribute('data-server-rendered')) {
    hydrateRoot(el, <App {...props} />)
  } else {
    createRoot(el).render(<App {...props} />)
  }
}

3. 验证 SSR 页面解析逻辑 #

在 ssr.tsx 中添加调试日志，确认页面是否能被正确加载：

resolve: (name) => {
  console.log('Loading SSR page:', name)
  return resolvePageComponent(
    `./pages/${name}.tsx`,
    import.meta.glob('./pages/**/*.tsx')
  )
},

启动 SSR 服务后访问页面，查看终端是否输出对应日志，判断页面解析是否正常。

4. 检查 Blade 模板配置 #

确保 resources/views/app.blade.php 正确输出 SSR 内容，核心代码如下：

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ config('app.name') }}</title>
    @vite(['resources/js/app.tsx', "resources/js/Pages/{$page['component']}.tsx"])
    @inertiaHead
</head>
<body class="font-sans antialiased">
    @inertia
</body>
</html>

确认 @inertia 指令无额外 HTML 干扰，且 @vite 引入路径正确。

5. 核对环境与配置 #

• 确认 .env 中 INERTIA_SSR_ENABLED=true
• 检查 config/inertia.php 的 SSR 配置：

'ssr' => [
    'enabled' => true,
    'url' => 'http://127.0.0.1:13714',
],

保证 URL 与 SSR 服务启动地址完全一致。

兜底方案 #

若以上步骤无效，删除 node_modules、vendor 目录，重新执行 npm install 和 composer install，再重新构建启动服务。

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