Nuxt应用SSR构建异常求助：CSR替代SSR渲染问题排查

核心问题分析 #

你的问题根源在于default.vue中的v-if="isPageReady"条件阻断了服务端渲染阶段的内容输出——SSG构建依赖服务端渲染生成静态HTML，但这个条件在服务端时isPageReady通常为false，导致页面内容被完全隐藏，最终生成的静态文件只有空占位div。而移除该条件后，又会出现客户端hydration完成前，未渲染的原始模板内容（如空白占位、未填充结构）闪烁的问题。

分步修复方案 #

1. 替换v-if为v-show（优先推荐） #

把模板中的v-if="isPageReady"改成v-show="isPageReady"：

<template>
  <div class="document-driven-page" v-show="isPageReady">
    <!-- 你的页面内容 -->
  </div>
</template>

• v-show会在服务端渲染时输出完整的HTML内容，仅通过CSS控制显示/隐藏；客户端hydration完成后再切换显示状态，既保证SSG生成完整的SSR内容（利于SEO），又避免了未渲染内容的闪烁。
• 注意：该方案会让服务端输出的HTML包含隐藏的完整内容，对文档类站点来说，体积增加的影响可以忽略。

2. 通过全局样式控制加载状态（兼容复杂场景） #

如果必须保留条件渲染逻辑，可通过控制全局样式在服务端隐藏内容，客户端加载完成后解除隐藏：

<script setup>
const isPageReady = ref(false)
const head = useHead({
  htmlAttrs: {
    class: computed(() => isPageReady.value ? '' : 'page-loading')
  }
})

// 页面数据加载完成后标记状态为就绪
onMounted(async () => {
  await loadRequiredPageData() // 替换成你的数据加载逻辑
  isPageReady.value = true
})
</script>

<style>
.page-loading .document-driven-page {
  display: none;
}
</style>

• 服务端渲染时，根html标签会带上page-loading类，隐藏页面内容；客户端加载完成后移除该类，显示完整内容。
• 这种方式既保证了SSG生成完整的可索引HTML，又避免了未渲染内容的闪烁问题。

3. 确认Nuxt SSG配置正确性 #

检查nuxt.config.ts中的静态生成配置是否正确：

export default defineNuxtConfig({
  ssr: true, // SSG依赖SSR开启，必须设置为true
  nitro: {
    prerender: {
      crawlLinks: true, // 自动爬取站点内链接生成静态页面
      routes: ['/', '/ja/getting-started/introduction/'] // 手动指定需要预渲染的核心路由
    }
  }
})

• 构建前建议先清除缓存：执行npx nuxi clean后再运行npm run generate，避免旧配置影响。

验证修复效果 #

构建完成后，查看.output/public目录下对应路由的HTML文件（如ja/getting-started/introduction/index.html），确认body内包含完整的渲染后内容而非空div；部署后查看页面源码，应能看到可索引的文本内容，同时客户端加载时不会出现未渲染内容的闪烁。

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