Nuxt.js自定义错误页失效及404转500问题求助

问题现象 #

在Nuxt.js项目中访问不存在的URL时，自定义error.vue页面无法稳定生效：

• 生产环境多数时候返回500服务器错误，偶尔才显示自定义错误页
• 开发环境频繁出现Maximum call stack size exceeded栈溢出错误，而非预期的404页面

相关代码与配置 #

自定义error.vue页面代码 #

<template>
  <div class="error-page">
    <div class="page-not-found" v-if="error.statusCode === 404">
      <div class="image">
        <img src="/images/page-not-found.png" alt="page not found">
      </div>
      <h1 class="text-capitalize font-weight-bold">
        {{ $t('notFound.error404') }}
      </h1>
      <p class="info my-3 my-lg-4">
        {{ $t('notFound.error404Info') }}
      </p>
    </div>
    <h1 class="text-capitalize font-weight-bold"  v-else-if="error.statusCode === 500">
      {{ $t('notFound.error500') }}
    </h1>
    <h1 class="text-capitalize font-weight-bold"  v-else>
      {{ $t('notFound.error500') }}
    </h1>
    <NuxtLink class="home-back text-capitalize mb-lg-3" :to="localePath('/')">
    {{ $t('notFound.home') }}
    </NuxtLink>
  </div>

</template>

<script>
export default {
  props: ['error']
}
</script>

<style lang="scss" scoped>
//removed to minimize the code
</style>

补充说明 #

• 测试时使用随机URL字符串（如trrrrr）
• 开发环境偶尔能显示自定义404页，但多数时候触发栈溢出错误

PWA配置 #

pwa: {
  meta: {
    title: "example",
    author: "example",
  },
  icon: { purpose: "any" },
  manifest: {
    display: "standalone",
    name: "example",
    lang: "en",
    useWebmanifestExtension: true,
    theme_color: "#01bac6",
  },
},

疑问 #

1. 为什么自定义错误页无法稳定生效？
2. 访问不存在的页面为什么返回500而非404错误？

问题解答 #

1. 自定义错误页不稳定/栈溢出的原因 #

递归错误触发死循环

开发环境的栈溢出错误，核心原因是错误页自身抛出了新错误，导致Nuxt不断重复渲染error.vue进入递归循环：

• 错误页中使用的$t国际化方法，如果notFound.error404等key未在国际化配置中定义，会抛出错误，触发Nuxt再次渲染错误页
• 静态图片/images/page-not-found.png如果不存在，会触发静态资源404请求，若服务器对静态资源错误的处理逻辑异常，会再次调用错误页
• localePath方法依赖i18n配置，若i18n插件配置出错，跳转逻辑会抛出错误，引发循环渲染

生产环境500错误的关联

生产环境的500错误，是因为上述递归错误在服务器端渲染时被捕获，Nuxt将渲染错误判定为内部服务器错误，返回500状态码，而非原本的404。

2. 返回500而非404的原因 #

• 当Nuxt尝试渲染404错误页时，error.vue自身抛出未捕获的错误，服务器将这个渲染错误优先级提升为内部服务器错误，用500状态码覆盖了原本的404
• 另一种可能是路由/服务器配置异常：比如服务器未将所有不存在的路由转发给Nuxt处理，或Nuxt路由匹配逻辑出错，导致服务器直接返回500

修复步骤 #

1. 排查error.vue中的潜在错误

   • 验证国际化key：确认notFound命名空间下的error404、error404Info、error500、home所有key都已配置
   • 检查静态资源路径：确认page-not-found.png存在于项目static/images目录下（Nuxt静态资源默认存放路径）
   • 校验i18n配置：确保localePath('/')能正确生成首页路由，i18n插件无配置错误

2. 添加错误捕获逻辑
   在error.vue中添加错误日志，便于定位问题，同时避免递归：

<script>
export default {
  props: ['error'],
  mounted() {
    console.error('Error page triggered with:', this.error)
  },
  async asyncData({ error: nuxtError }) {
    if (nuxtError) {
      console.error('SSR error in error page:', nuxtError)
    }
  }
}
</script>

3. 验证生产环境服务器配置

   • 确保服务器（如Nginx）将所有路由请求转发给Nuxt入口文件，无静态资源或路由的误拦截
   • 检查serverMiddleware或自定义中间件，确认无修改错误状态码的异常逻辑

4. 简化测试定位问题
   先将error.vue简化到最基础结构，验证是否能稳定显示404：

<template>
  <div class="error-page">
    <h1 v-if="error.statusCode === 404">404 页面不存在</h1>
    <h1 v-else>500 服务器错误</h1>
    <a href="/">返回首页</a>
  </div>
</template>

如果简化后正常工作，再逐步添加国际化、图片、跳转逻辑，逐个排查触发错误的模块。

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