Nuxt 3 404页面未找到错误处理及自定义404页面实现求助

为什么你的错误处理插件未生效 #

你之前创建的errorhandler.ts插件无法捕获H3Error: Page not found错误，核心原因是：nuxtApp.vueApp.config.errorHandler仅负责处理Vue组件树内部的客户端/服务端渲染错误，而路由未匹配的404错误属于Nitro服务器层的错误，不在Vue错误处理的覆盖范围内。

1. 抑制404错误日志输出 #

要避免每条404请求都生成日志，需要在Nitro服务器层捕获并处理这类错误，以下两种方式任选其一：

方式一：通过服务器中间件处理 #

在项目根目录创建server/middleware/handle-404.ts文件，代码如下：

export default defineEventHandler(async (event) => {
  try {
    // 继续处理请求，路由未匹配时会抛出404错误
    await send(event);
  } catch (error) {
    // 判定是否为404错误
    if (error instanceof Error && 'statusCode' in error && error.statusCode === 404) {
      // 标记响应状态码为404，同时阻止错误向上抛出
      event.res.statusCode = 404;
      return;
    }
    // 非404错误继续抛出，保留默认日志逻辑
    throw error;
  }
});

方式二：配置Nitro全局错误处理器 #

在项目根目录创建nitro.config.ts文件（若已存在则直接修改），添加全局错误处理逻辑：

export default defineNitroConfig({
  errorHandler: (error, event) => {
    if (error.statusCode === 404) {
      // 仅处理404错误，不输出冗余日志
      event.res.statusCode = 404;
      return { statusCode: 404, message: '页面未找到' };
    }
    // 其他错误按默认逻辑处理（保留日志）
    throw error;
  }
});

2. 创建自定义404页面 #

Nuxt3提供了极简的自定义404页面方案，直接在pages目录下创建[...notfound].vue文件即可：

<template>
  <div class="not-found-container">
    <h1>404</h1>
    <h2>页面未找到</h2>
    <p>你访问的链接不存在，请检查地址是否正确</p>
    <NuxtLink to="/" class="back-home-btn">返回首页</NuxtLink>
  </div>
</template>

<script setup>
// 确保服务器端返回404状态码
useHead({
  statusCode: 404
});
</script>

<style scoped>
.not-found-container {
  text-align: center;
  padding: 6rem 1rem;
  max-width: 600px;
  margin: 0 auto;
}

h1 {
  font-size: 6rem;
  color: #666;
  margin: 0;
}

h2 {
  font-size: 1.5rem;
  color: #333;
  margin: 0.5rem 0 1rem;
}

.back-home-btn {
  display: inline-block;
  margin-top: 1.5rem;
  padding: 0.75rem 1.5rem;
  background-color: #3b82f6;
  color: white;
  border-radius: 4px;
  text-decoration: none;
}
</style>

这个页面会自动匹配所有未定义的路由，无论是客户端路由跳转还是服务器端直接请求，都会渲染该页面并返回404状态码。

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