网站开发框架Koa的ctx.throw安全错误处理

在 Koa 应用里，如果你还在用 try-catch 包裹每个控制器然后手动返回 4xx 或 5xx 状态码，那你其实没有真正用对 Koa 的错误处理机制。ctx.throw 是 Koa 原生提供的最直接、最语义化的错误抛出方式，但它带来的安全问题远比表面看起来复杂。错误信息里包含的堆栈、文件路径、数据库查询语句，一旦泄露到前端，就是给攻击者递刀。所以，ctx.throw 的正确用法，绝不仅仅是“扔一个错误出去”这么简单，它是一整套“抛出-捕获-清洗-响应”的安全链路。

先看一段最常见的危险写法：

// 危险示例：直接将底层错误抛出
async function getUser(ctx) {
  try {
    const user = await db.query('SELECT * FROM users WHERE id = ?', ctx.params.id);
    if (!user) {
      ctx.throw(404, '用户不存在');
    }
    ctx.body = user;
  } catch (err) {
    ctx.throw(500, err.message); // 这里直接把原始错误信息暴露了
  }
}

ctx.throw 方法接受两个参数：状态码和消息体。当你调用 ctx.throw(500, err.message) 时，Koa 内部会创建一个带有 status 和 message 属性的 Error 对象，然后沿着中间件链向上抛出。如果全局错误处理中间件没有对错误信息做清洗，前端就会直接收到类似 “Table 'users' doesn't exist” 或者 “connect ECONNREFUSED 127.0.0.1:3306” 这样的消息。这些信息暴露了数据库表结构、内网 IP 地址和端口，属于严重的信息泄露漏洞。

更深层的风险在于，Node.js 的错误对象上还挂着 stack 属性。如果你在开发环境下习惯性地把 err.stack 也放进响应体，生产环境一旦忘记关掉，攻击者就能拿到完整的调用栈，里面可能包含文件系统绝对路径、使用的第三方包版本、甚至敏感的环境变量名称。Koa 默认的错误处理在非生产环境下会把堆栈信息返回给客户端，这个行为需要通过配置 NODE_ENV 环境变量来控制，但很多人只在启动命令里设置了环境变量，却没有在全局错误处理逻辑里做兜底判断。

正确的做法是建立一个“错误信息清洗层”。所有通过 ctx.throw 抛出的错误，都应该在这个层里被拦截、分类、脱敏，然后才返回给客户端。下面是一个生产级别的实现：

// 自定义错误类，区分业务错误和系统错误
class BusinessError extends Error {
  constructor(status, message, code) {
    super(message);
    this.status = status;
    this.code = code; // 业务错误码，用于前端精准处理
    this.expose = true; // 标记为可暴露给客户端的错误
  }
}

class SystemError extends Error {
  constructor(message, originalError) {
    super(message);
    this.status = 500;
    this.expose = false; // 系统错误不可暴露详情
    this.originalError = originalError; // 保留原始错误用于日志
  }
}

// 全局错误处理中间件
app.use(async (ctx, next) => {
  try {
    await next();
    // 处理404：如果没有任何中间件设置响应体且状态码为404
    if (ctx.status === 404 && !ctx.body) {
      ctx.throw(404, '请求的资源不存在');
    }
  } catch (err) {
    // 第一步：判断错误是否由 ctx.throw 抛出
    // ctx.throw 抛出的错误 status 会是设置的值
    const status = err.status || 500;
    
    // 第二步：区分环境，决定是否暴露详细信息
    const isProduction = process.env.NODE_ENV === 'production';
    
    if (err.expose) {
      // 业务错误：安全地返回给客户端
      ctx.status = status;
      ctx.body = {
        success: false,
        code: err.code || status,
        message: err.message,
      };
    } else if (status >= 500) {
      // 系统错误：记录完整日志，返回通用消息
      console.error('[SystemError]', {
        message: err.message,
        stack: err.stack,
        originalError: err.originalError ? err.originalError.message : null,
        requestId: ctx.state.requestId, // 用于日志追踪
        url: ctx.url,
        method: ctx.method,
      });
      
      ctx.status = 500;
      ctx.body = {
        success: false,
        code: 500,
        message: isProduction ? '服务器内部错误，请稍后重试' : err.message,
        // 生产环境返回一个 requestId，方便用户反馈问题时定位日志
        requestId: isProduction ? ctx.state.requestId : undefined,
      };
    } else {
      // 4xx 客户端错误：通常是参数校验等，可以返回具体信息
      ctx.status = status;
      ctx.body = {
        success: false,
        code: status,
        message: err.message,
      };
    }
    
    // 关键：阻止 Koa 默认的错误处理再次触发
    ctx.app.emit('error', err, ctx);
  }
});

这个中间件做了几件关键的事：第一，通过自定义的 expose 属性区分哪些错误可以给客户端看，哪些必须隐藏。第二，5xx 系统错误在生产环境下只返回一句通用提示，但完整日志会记录到服务器端，包含堆栈和原始错误信息。第三，引入了 requestId 机制，通过一个 UUID 生成中间件给每个请求打上唯一标识，用户看到错误时可以把这个 ID 提供给技术人员，方便在日志里快速定位问题。第四，手动调用 ctx.app.emit('error', err, ctx) 来触发 Koa 的 error 事件，这样你注册的日志监听器仍然能正常工作，但响应体已经被你接管了。

ctx.throw 的第二个参数不仅仅是字符串，它可以是对象、甚至是 Error 实例。这个灵活性如果用不好，也会造成信息泄露。比如有人会这样写：

// 错误做法：把数据库返回的错误对象直接丢进去
ctx.throw(400, dbError);

如果 dbError 是一个包含 sqlMessage、sqlState 等字段的对象，Koa 会把这个对象的属性合并到响应体的 message 字段或者直接作为响应体。正确做法是永远只传递你自己定义的、对客户端有意义的字符串或对象：

// 正确做法：只传递清洗过的信息
ctx.throw(400, '请求参数不合法', { 
  code: 'INVALID_PARAM',
  fields: ['email', 'password'] // 只告诉前端哪些字段有问题，不说为什么
});

关于 HTTP 状态码的选择，很多开发者习惯在业务校验失败时也扔 400，但其实更精细的状态码能让前端和网关层做出更准确的反应。参数缺失用 400，认证失败用 401，权限不足用 403，资源不存在用 404，请求格式正确但业务逻辑不满足用 422，请求频率过高用 429。Koa 的 ctx.throw 完全支持这些状态码，你只需要在抛出时指定正确的数字即可。这种规范性本身就是安全的一部分，因为模糊的状态码会导致前端误判错误类型，进而可能执行不安全的降级逻辑。

ctx.throw 只能处理同步抛出的错误，或者在 async 函数中被 await 的错误。如果你的代码里有未捕获的 Promise rejection，或者事件回调里的错误，ctx.throw 是拦截不到的。这些未处理的错误会导致 Node.js 进程崩溃，或者被 Koa 默认的错误处理以不恰当的方式返回给客户端。你需要在应用入口处注册全局的未捕获异常处理器：

// 捕获未处理的 Promise rejection
process.on('unhandledRejection', (reason, promise) => {
  console.error('[UnhandledRejection]', {
    message: reason.message,
    stack: reason.stack,
  });
  // 不要在这里直接退出进程，记录日志后让应用继续运行
  // 但如果是关键错误，应该触发优雅关闭
});

// 捕获未捕获的同步异常
process.on('uncaughtException', (err) => {
  console.error('[UncaughtException]', {
    message: err.message,
    stack: err.stack,
  });
  // 未捕获的异常意味着进程状态可能已经不一致，建议优雅关闭
  process.exit(1);
});

但仅仅有全局捕获还不够。在 Koa 中间件里，任何在 await 之外抛出的错误，或者在不带 await 的 Promise 链里抛出的错误，都不会被 try-catch 捕获。这就要求开发者在编写中间件时，确保所有异步操作都被 await 包裹，或者在事件监听器里手动调用 ctx.throw 而不是直接 throw。一个容易被忽略的场景是流式处理：当你使用 fs.createReadStream 读取文件并 pipe 到 ctx.body 时，流上的 error 事件必须被监听，否则错误会变成未捕获异常。

即使你做了全局的错误清洗，错误对象本身在内存中仍然可能携带敏感数据。比如你在一个中间件里从请求中解析出了用户的手机号、身份证号，然后这个中间件抛出了一个错误，错误对象的 message 里虽然被你清洗了，但错误发生时的上下文变量仍然在闭包中。如果后续有日志记录逻辑把这些变量序列化输出，敏感数据就会出现在日志文件里。解决这个问题需要在日志记录环节做二次脱敏：

// 日志脱敏工具函数
function sanitizeForLogging(obj) {
  const sensitiveFields = ['password', 'token', 'secret', 'phone', 'idCard', 'email'];
  const sanitized = { ...obj };
  
  for (const field of sensitiveFields) {
    if (sanitized[field]) {
      sanitized[field] = '*REDACTED*';
    }
  }
  
  // 递归处理嵌套对象
  for (const key in sanitized) {
    if (typeof sanitized[key] === 'object' && sanitized[key] !== null) {
      sanitized[key] = sanitizeForLogging(sanitized[key]);
    }
  }
  
  return sanitized;
}

// 在错误日志记录时使用
console.error('[Error]', sanitizeForLogging({
  message: err.message,
  requestBody: ctx.request.body,
  requestQuery: ctx.query,
}));

这个脱敏函数需要在记录任何请求上下文之前调用。更好的做法是把脱敏逻辑集成到日志中间件里，确保所有日志输出都经过清洗，避免某个开发者在调试时直接 console.log 了请求体而导致敏感数据泄露到标准输出。

ctx.throw 本身只是一个抛出机制，它需要配合一套完整的业务错误码体系才能发挥最大价值。错误码的设计应该遵循“前端可消费”原则：每个错误码对应一种前端可以据此执行特定逻辑的场景。比如 “USER_NOT_FOUND” 可以让前端跳转到注册页，“TOKEN_EXPIRED” 可以触发自动刷新令牌，“RATE_LIMITED” 可以显示倒计时。这些错误码通过 ctx.throw 的第三个参数传递：

// 定义错误码常量
const ErrorCodes = {
  USER_NOT_FOUND: { status: 404, code: 'USER_NOT_FOUND', message: '用户不存在' },
  TOKEN_EXPIRED: { status: 401, code: 'TOKEN_EXPIRED', message: '登录已过期，请重新登录' },
  PERMISSION_DENIED: { status: 403, code: 'PERMISSION_DENIED', message: '没有访问权限' },
  RATE_LIMITED: { status: 429, code: 'RATE_LIMITED', message: '请求过于频繁，请稍后再试' },
};

// 在业务逻辑中使用
async function getUserProfile(ctx) {
  const user = await User.findById(ctx.params.id);
  if (!user) {
    const err = ErrorCodes.USER_NOT_FOUND;
    ctx.throw(err.status, err.message, { code: err.code });
  }
  
  if (user.isPrivate && ctx.state.currentUser.id !== user.id) {
    const err = ErrorCodes.PERMISSION_DENIED;
    ctx.throw(err.status, err.message, { code: err.code });
  }
  
  ctx.body = user;
}

这种集中定义错误码的方式有多个好处：前端可以建立错误码映射表来统一处理错误；后端可以确保同一类错误返回的状态码和消息保持一致；测试时可以针对特定错误码编写断言。而且，错误码定义本身不包含任何实现细节，不会泄露系统内部信息。

全局错误处理中间件必须放在所有其他中间件之前注册，这是 Koa 洋葱模型决定的。但很多人忽略了另一个顺序问题：错误处理中间件之后的中间件抛出的错误，它还能捕获吗？答案是能，因为 Koa 的中间件执行是栈式嵌套的。但有一个例外：如果你在错误处理中间件里没有调用 await next()，而是直接 return 了，那后续中间件根本不会执行。所以错误处理中间件的结构必须是：

app.use(async (ctx, next) => {
  try {
    await next(); // 必须 await，让后续所有中间件在这个 try 块里执行
  } catch (err) {
    // 处理错误
  }
});

另外，如果你使用了 koa-router 这样的路由中间件，它内部有自己的错误处理逻辑。当路由匹配失败时，koa-router 不会抛出错误，而是简单地不设置响应体。这就是为什么在全局错误处理中间件里需要检查 ctx.status === 404 && !ctx.body 的原因——把路由未匹配的情况也纳入统一的错误处理流程。

ctx.throw 是 Koa 错误处理体系里最锋利的工具，但锋利意味着容易伤到自己。安全使用它的核心原则可以归结为三条：永远在全局清洗层里剥离敏感信息再返回给客户端；永远区分业务错误和系统错误，只暴露前者；永远记录完整的错误上下文到服务器日志，但记录前必须脱敏。做到这三点，你就能在享受 ctx.throw 带来的代码简洁性的同时，守住应用的安全底线。