Nuxt SSR中Vue水合失败问题排查求助

针对报错 Attempting to hydrate existing markup but container is empty. Performing full mount instead.，按以下步骤排查：

1. 确认服务端渲染的HTML输出是否有效 #

• 直接查看页面源码，找到你用于hydrate的目标容器（比如id="root"的元素），检查内部是否有SSR生成的完整HTML内容。如果为空，说明服务端渲染逻辑存在问题：
  • 排查服务端路由是否匹配当前请求，比如服务端是否正确处理了客户端请求的路由路径；
  • 在服务端渲染代码中添加日志，输出最终生成的HTML字符串，确认是否因组件渲染报错、数据预取失败等导致内容为空。

2. 验证客户端Hydrate的容器配置 #

• 确认客户端调用hydrateRoot（或旧版hydrate）时，传入的容器元素是否正确：
  • 检查容器选择器是否拼写错误（比如把#root写成.root）；
  • 确保hydrate逻辑在DOM加载完成后执行，比如包裹在DOMContentLoaded事件回调中，避免DOM未解析完成时找不到容器。

3. 排查服务端与客户端的内容不匹配 #

即使容器看起来有内容，也可能因两端渲染内容不一致触发该报错：

• 检查环境变量是否一致：比如服务端使用process.env.SSR=true控制渲染逻辑，客户端是否同步了该变量；
• 排查组件中的浏览器专属API：确保服务端渲染时，window、document等API仅在客户端执行（比如用useEffect或typeof window !== 'undefined'判断），避免服务端渲染出错导致HTML不完整；
• 核对路由配置：确保服务端路由与客户端路由的规则完全一致，避免两端渲染不同页面。

4. 检查异步数据预取逻辑 #

• 服务端必须确保组件依赖的异步数据已完全加载后再渲染，否则服务端会渲染空/加载状态的内容，客户端hydrate时数据已就绪，导致内容不匹配；
• 确认服务端预取的数据是否通过全局变量（如window.__INITIAL_STATE__）传递给客户端，且客户端正确读取并初始化状态。

5. 逐步定位问题组件 #

• 先简化页面，仅渲染最基础的组件（比如<div>Test SSR</div>），若报错消失，再逐步添加其他组件，直到报错重现，以此定位问题组件；
• 开启React的StrictMode，开发模式下它会检测hydration不匹配的细节，并抛出更明确的警告。

6. 核对依赖版本与构建配置 #

• 确认react与react-dom版本完全一致，版本不兼容可能导致hydration逻辑异常；
• 检查构建工具（webpack/vite等）的客户端与服务端构建配置，确保两端的代码编译规则一致，避免服务端构建时排除的代码在客户端出现差异。

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