Nuxt3静态生成时@nuxt/content标签页返回404错误求助

我有一个基于Nuxt3 + @nuxt/content的站点，此前运行正常。近期更新依赖后，执行nuxt generate时，动态生成的articles/tags/*页面出现404错误——预渲染阶段加载这些页面时，会尝试查询对应JSON文件，但系统查找的文件实际并未生成（生成的文件名与请求的不匹配）。

环境依赖 #

% pnpm ls
dependencies:
h3 1.11.1
nuxt-icon 0.6.10
rehype-katex 7.0.0
remark-math 6.0.0
vue-composable 1.0.0-beta.24

devDependencies:
@heroicons/vue 2.1.3
@nuxt/content 2.12.1
@nuxt/image 1.4.0
@nuxtjs/color-mode 3.3.3
@nuxtjs/tailwindcss 6.11.4
@tailwindcss/typography 0.5.10
@types/node 18.19.26
nuxt 3.11.1
vue-gtag 2.0.1

Nuxt配置（nuxt.config.ts） #

export default defineNuxtConfig({
...
  content: {
    documentDriven: true,
    markdown: {
      anchorLinks: false,
      remarkPlugins: [
        'remark-math'
      ],
      rehypePlugins: [
        'rehype-katex'
      ]
    }
  },
})

预渲染错误日志 #

Errors prerendering:
  ├─ /api/_content/query/wyAI10pxT3.1711366156783.json (1ms)                              
  │ ├── Error: [404] Document not found!
  │ └── Linked from /articles/tags/programming
  ├─ /api/_content/query/3wG2XPSOCP.1711366156783.json (1ms)                               
  │ ├── Error: [404] Document not found!
  │ └── Linked from /articles/tags/async
  ├─ /api/_content/query/V075q5TyMx.1711366156783.json (1ms)                               
  │ ├── Error: [404] Document not found!
  │ └── Linked from /articles/tags/society & culture
  ├─ /api/_content/query/oeZgEOdCy4.1711366156783.json (2ms)                               
  │ ├── Error: [404] Document not found!

标签页组件代码（[tag].vue） #

<script setup lang="ts">
const route = useRoute()
const tag = route.params.tag

const { data: queryResult, pending, error, refresh } =
  await useAsyncData(`tag-query-${tag}`,
                     () => {
                       return queryContent('/articles')
                         .where({
                           tags: { $contains: tag }
                         })
                         .find()
  })
const articles = queryResult.value
</script>

<template>
  <NuxtLayout>
    <h1>Articles tagged with {{ tag }}</h1>
    <div class="layout flex flex-wrap gap-5">
      <ArticlesListItem v-for="(article, index) in articles" :key="index" :article="article" />
    </div>
  </NuxtLayout>
</template>

排查建议 #

• 检查版本兼容性：当前@nuxt/content 2.12.1与Nuxt 3.11.1可能存在兼容问题，尝试降级@nuxt/content到2.11.x或升级到最新兼容版本，依赖版本不匹配可能导致查询哈希生成逻辑异常。
• 临时禁用documentDriven模式：在nuxt.config.ts中设置content.documentDriven: false，重新执行nuxt generate，验证是否因自动路由处理与手动动态路由冲突导致问题。
• 修正useAsyncData缓存键：将缓存键改为tag-query-${encodeURIComponent(tag)}，避免特殊字符（如society & culture中的&）干扰哈希生成；同时可给queryContent添加cache: false参数，强制重新查询。
• 手动指定预渲染路由：在nuxt.config.ts的nitro配置中添加所有标签页路由，确保预渲染阶段能正确生成对应查询文件：

  export default defineNuxtConfig({
    nitro: {
      prerender: {
        routes: [
          '/articles/tags/programming',
          '/articles/tags/async',
          '/articles/tags/society & culture'
        ]
      }
    }
  })
  

• 清理缓存后重建：执行pnpm nuxt clean，删除.nuxt和.output目录，再重新执行nuxt generate，排除旧缓存文件影响。
• 验证Markdown标签格式：确认所有文章的tags字段为字符串数组格式，无格式错误导致查询匹配失败。

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