Nuxt 4搭配@nuxt/content生产环境刷新/直连页面显示‘内容未找到’

环境信息 #

• 操作系统：macOS
• @nuxt/content: ^3.6.3
• Nuxt: ^4.0.3
• Node版本：24

问题描述 #

在使用@nuxt/content的Nuxt 4项目中，生产环境下直接访问URL或按F5刷新内容页面时，页面显示“内容未找到”；但通过站点内的<NuxtLink>导航到同一页面时，内容加载渲染正常。该问题仅出现在生产构建环境，本地开发环境无法复现。

复现步骤 #

1. 执行npm run build构建Nuxt生产项目
2. 执行npm run prod启动生产服务器
3. 通过内部<NuxtLink>导航到内容渲染页面，内容加载正常
4. 在同一页面执行硬刷新（F5），页面短暂显示内容后出现“内容未找到”提示
5. 打开新浏览器标签页粘贴内容页面的URL，页面直接显示“内容未找到”
6. 页面刷新或直接导航时，API端点/api/_content返回404错误

推测原因 #

该问题与服务端渲染（SSR）及客户端水合过程处理内容API请求的方式有关——初始服务端渲染的HTML包含内容，但后续客户端请求失败。强制刷新（cmd+shift+r）时，页面会先短暂显示内容，随后出现“内容未找到”提示。

解决方案建议 #

1. 升级依赖版本 #

当前使用的@nuxt/content ^3.6.3版本较旧，尝试升级到最新兼容Nuxt 4的版本，新版本可能已修复SSR与客户端水合的匹配问题。执行命令：

npm install @nuxt/content@latest

2. 检查Nuxt配置中的内容路由与API路径 #

在nuxt.config.ts中确认content模块的配置，确保API路径正确，且生产环境下服务端能正确处理/api/_content请求：

export default defineNuxtConfig({
  modules: ['@nuxt/content'],
  content: {
    base: '/api/_content' // 确认base路径配置正确
  }
})

3. 限制内容请求仅在服务端执行 #

在页面组件中使用useAsyncData并设置server: true，确保内容仅在服务端获取，避免客户端重复发起API请求：

<script setup>
const { data: content } = await useAsyncData('content-key', () => {
  return queryContent('/target-content-path').findOne()
}, { server: true })
</script>

4. 检查生产服务器路由映射 #

如果是SSR部署，确认服务器未拦截/api/_content请求，确保请求能正确转发到Nuxt服务；如果使用静态站点生成，执行nuxt generate而非nuxt build，确保生成所有内容页面的静态文件。

5. 配置内容缓存策略 #

启用@nuxt/content的缓存，确保服务端渲染的内容能被客户端复用，避免无效的API请求：

export default defineNuxtConfig({
  content: {
    cache: {
      maxAge: 60 * 60 * 24 // 缓存1天，可根据需求调整
    }
  }
})

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