使用Nuxt3+Storyblok生成纯静态站点遇API调用问题求助

以下是针对你遇到的「静态生成后首次加载仍触发Storyblok API调用」问题的排查方向和解决步骤：

1. 检查Nuxt静态预渲染配置是否覆盖所有路由 #

确保nuxt.config.ts中的nitro.prerender配置正确覆盖了你所有需要预渲染的页面：

export default defineNuxtConfig({
  nitro: {
    prerender: {
      // 启用自动爬取链接，确保所有内部路由被预渲染
      crawlLinks: true,
      // 手动补充爬虫无法覆盖的路由（如动态路由、隐藏路由）
      routes: ['/', '/about', '/blog/[slug]']
    }
  }
})

如果存在动态路由（如/blog/[slug]），你需要在nitro.prerender.routes中列出所有实际存在的slug，或者编写一个prerender.ts脚本在构建时动态获取所有slug并添加到预渲染列表中。

2. 修正Storyblok模块的静态生成配置 #

确保@storyblok/nuxt模块配置启用了静态数据预取，并且使用发布版内容：

export default defineNuxtConfig({
  modules: ['@storyblok/nuxt'],
  storyblok: {
    // 构建时使用发布版token，避免请求草稿内容
    accessToken: process.env.STORYBLOK_PUBLISHED_TOKEN,
    apiOptions: {
      // 指定你的Storyblok区域（如'us'或'eu'）
      region: 'eu'
    },
    // 禁用Storyblok Bridge（静态站点不需要实时编辑功能）
    bridge: false,
    // 强制静态生成时预取数据
    useStaticFetch: true
  }
})

注意：构建环境必须配置STORYBLOK_PUBLISHED_TOKEN环境变量，否则构建阶段无法获取数据，只能在客户端发起请求。

3. 调整组件中数据获取的逻辑 #

确保useAsyncStoryblok仅在构建/服务器端执行，避免客户端重复请求：

<template>
  <div v-if="story">
    <h1>{{ story.content.title }}</h1>
  </div>
</template>

<script setup>
// 仅在服务器/静态构建阶段获取数据
const { story } = await useAsyncStoryblok('home-page', {
  version: 'published',
  // 禁用客户端缓存，确保构建时直接写入HTML
  cache: false
})
</script>

同时检查生成的dist目录下的HTML文件，确认页面内容已经包含Storyblok返回的文本（而非空容器），如果HTML中已有内容但仍有API请求，说明客户端逻辑重复触发了数据获取。

4. 禁用客户端的额外数据请求 #

如果上述配置都正确，但仍有API调用，可能是Storyblok模块的客户端逻辑在执行。可以通过以下方式强制客户端复用静态数据：

• 在页面组件中使用useStaticState存储预取的Storyblok数据，客户端直接读取该状态而非发起请求。
• 确保ssr: true在nuxt.config.ts中被设置（静态生成依赖SSR模式预渲染）。

5. 验证Netlify构建过程 #

查看Netlify的构建日志，确认npm run generate阶段是否有Storyblok API请求的记录：

• 如果构建日志中没有请求记录，说明构建阶段未获取数据，客户端只能自行请求，此时需要检查环境变量是否正确配置。
• 如果构建日志中有请求记录，但生成的HTML仍无内容，说明数据未被正确注入到静态页面中，需要检查组件逻辑是否正确处理了异步数据。

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