如何在Fastify v3中返回自定义错误？含v4兼容方案及代码实现请求

Fastify v3 和 v4 均支持自定义错误响应格式，核心是通过 setErrorHandler 覆盖默认的错误处理逻辑——默认处理器会强制将错误转换为固定结构，因此需要自定义处理器来输出包含自定义字段的响应。

Fastify v3 实现代码 #

const fastify = require('fastify')({ logger: true })

// 覆盖默认错误处理器
fastify.setErrorHandler((error, request, reply) => {
  // 构建基础错误响应结构
  const errorResponse = {
    statusCode: error.statusCode || 500,
    error: error.error || 'Internal Server Error',
    message: error.message || 'An unexpected error occurred'
  }

  // 若错误对象携带自定义字段，添加到响应中
  if (error.myCustomError) {
    errorResponse.myCustomError = error.myCustomError
  }

  // 发送自定义响应
  reply.status(errorResponse.statusCode).send(errorResponse)
})

// 测试路由：抛出带自定义字段的错误
fastify.get('/test', (request, reply) => {
  const err = new Error('Missing property blah-blah')
  err.statusCode = 400
  err.error = 'Bad Request'
  err.myCustomError = 'yo yo I am custom'
  throw err
})

// 启动服务
fastify.listen(3000, (err) => {
  if (err) {
    fastify.log.error(err)
    process.exit(1)
  }
})

Fastify v4 实现代码 #

v4 的错误处理器 API 与 v3 基本一致，仅在启动方式等细节上略有差异：

import fastify from 'fastify'
const app = fastify({ logger: true })

// 自定义错误处理器
app.setErrorHandler((error, request, reply) => {
  const errorResponse = {
    statusCode: error.statusCode ?? 500,
    error: error.error ?? 'Internal Server Error',
    message: error.message ?? 'An unexpected error occurred'
  }

  if (error.myCustomError) {
    errorResponse.myCustomError = error.myCustomError
  }

  reply.status(errorResponse.statusCode).send(errorResponse)
})

// 测试路由
app.get('/test', (request, reply) => {
  const err = new Error('Missing property blah-blah')
  err.statusCode = 400
  err.error = 'Bad Request'
  err.myCustomError = 'yo yo I am custom'
  throw err
})

// 启动服务
app.listen({ port: 3000 }, (err) => {
  if (err) {
    app.log.error(err)
    process.exit(1)
  }
})

补充说明 #

• 若需要处理 schema 验证类错误，可在错误处理器中读取 error.validation 属性，将验证详情添加到自定义响应中；
• onError 钩子主要用于错误日志记录或前置处理，无法直接修改响应内容，修改响应必须通过 setErrorHandler；
• 抛出错误时需确保错误对象携带所需的自定义属性，处理器才能识别并添加到响应结构中。

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