企业官网建设流程全解析

• 文档
• 教程
• 后端

导读

本文基于 Node.js 最佳实践清单（Node Best Practices）中「只使用内置 Error 对象」这一条实践展开。在 Node.js 应用中，错误的抛出方式五花八门——有人抛字符串、有人自定义十余种错误类，导致代码库内错误形态混乱、难以排查。读完本文，你将掌握如何统一使用Error对象、如何借助上下文属性与 StackTrace 提升排障效率，以及如何仅通过一次扩展定义AppError基类，配合仓库中的集中式错误处理、操作型/程序员错误区分等姊妹实践，搭建一套清晰、可维护的应用级错误处理体系。

一、为什么「只使用内置 Error 对象」是必须的

JavaScript 是一门"天生宽容"的语言，加上其丰富的代码流选择（EventEmitter、Callback、Promise、async/await 等），开发者抛出错误的方式也因此千差万别：有人抛字符串，有人自定义自己的类型。这种混乱会带来两个直接后果：

1. 错误形态不统一：你的代码、第三方库、同事的模块各自为政，错误处理逻辑无法复用；
2. 关键信息丢失：字符串等非 Error 值不携带 StackTrace、name、message 等标准属性，出问题后无从定位。

使用 Node.js 内置的Error对象（见 useonlythebuiltinerror.md），可以同时解决这两个问题：

• 在你的代码与第三方库之间保持一致性（uniformity）；
• 天然保留StackTrace等具有排障价值的信息；
• 抛出异常时，按惯例为错误补充上下文属性，如错误名称（name）和关联的 HTTP 状态码。

Node.js 官方文档对此有明确说明：Node.js 抛出的所有 JavaScript 错误与系统错误，都继承自或直接是标准 JavaScriptError类的实例，并且保证至少提供该类的全部属性；Error对象会捕获一个"堆栈追踪"（stack trace），标明 Error 被实例化处的代码位置，并可携带错误的文本描述。这意味着，遵守内置Error协议，就是与 Node.js 自身的错误体系对齐。

二、正确做法：在各类代码流中抛出 Error 对象

无论代码是同步函数、EventEmitter 事件还是 Promise，错误都应通过new Error(...)抛出（或通过emit('error', ...)传递）。以下代码来自 useonlythebuiltinerror.md 的正例：

// 在普通函数中抛出 Error，无论同步还是异步 if (!productToAdd) throw new Error('How can I add new product when no value provided?'); // 从 EventEmitter 中"抛出"Error const myEmitter = new MyEmitter(); myEmitter.emit('error', new Error('whoops!')); // 从 Promise 中"抛出"Error const addProduct = async (productToAdd) => { try { const existingProduct = await DAL.getProduct(productToAdd.id); if (existingProduct !== null) { throw new Error('Product already exists!'); } } catch (err) { // ... } };

值得注意最后一段 Promise 代码：throw位于async函数内部的try块中，异常会被catch (err)捕获并交给调用方处理。这与仓库中另一条实践 asyncerrorhandling.md 一脉相承——用 Promise 链或 async/await 的try/catch/finally收敛错误，而不是散落各处的回调判错。

三、反模式：永远不要抛出字符串

最常见的错误做法是直接抛出一个字符串：

// 抛字符串会丢失所有堆栈信息和其他重要的数据属性 if (!productToAdd) throw ('How can I add new product when no value provided?');

字符串没有任何堆栈追踪信息，也没有可供instanceof判别的类型身份。devthought.com 的博客尖锐地指出："字符串不是错误"——向调用方传字符串而非错误对象，会降低模块间的互操作性（interoperability），破坏那些可能正在执行instanceof Error检查、或希望获取更多错误细节的 API 契约；而错误对象在现代 JavaScript 引擎中，除了保存传入构造函数的 message 之外，还具备非常有趣的属性（即 StackTrace、cause 等）。

四、更进一步：只扩展一次内置 Error，得到 AppError

统一抛new Error('...')只是第一步。为了在错误中携带业务上下文（错误名、HTTP 状态码、是否可操作等），实践中通常扩展Error基类。但这里有一个重要的"度"：

• ❌不要为每种错误各扩展一次（例如 DbError、HttpError、ValidationError……），这会产生大量几乎相同、且与Error契约无本质差别的类型，徒增维护成本；
• ✅只扩展一次，定义一个覆盖所有应用级错误的AppError，通过构造参数来区分不同错误种类。

machadogj 的博客观点与此一致："从 Error 继承并不会带来太多额外价值"——诚然你可以继承并创造自己的HttpError、DbError等类，但这耗时且收益有限（除非你真的在用类型做文章）；有时你只是想加一条消息并保留内部错误，有时则想用参数扩展错误信息。

4.1 JavaScript 版本（ES5 风格构造器）

以下示例展示了如何从 Node 的Error派生出集中式错误对象：

// 从 Node 的 Error 派生的集中式错误对象 function AppError(name, httpCode, description, isOperational) { Error.call(this); Error.captureStackTrace(this); this.name = name; //...此处可继续赋值其他属性 } AppError.prototype = Object.create(Error.prototype); AppError.prototype.constructor = AppError; module.exports.AppError = AppError; // 客户端抛出一个异常 if (user == null) throw new AppError(commonErrors.resourceNotFound, commonHTTPErrors.notFound, 'further explanation', true)

要点拆解：

• Error.call(this)在实例上执行基类初始化，确保 message 等属性正确挂载；
• Error.captureStackTrace(this)让 V8 在当前实例上捕获 StackTrace，而不是在内部包装函数处捕获，保证堆栈指向真正的抛出点；
• AppError.prototype = Object.create(Error.prototype)建立原型继承链；
• 构造参数isOperational用于标记错误类型，这是仓库中 operationalvsprogrammererror.md 的核心概念——操作型错误（如外部服务连不上）可安全处理，程序员错误则应触发进程重启。

4.2 TypeScript 版本（class + new.target）

// 从 Node 的 Error 派生的集中式错误对象 export class AppError extends Error { public readonly name: string; public readonly httpCode: HttpCode; public readonly isOperational: boolean; constructor(name: string, httpCode: HttpCode, description: string, isOperational: boolean) { super(description); Object.setPrototypeOf(this, new.target.prototype); // 恢复原型链 this.name = name; this.httpCode = httpCode; this.isOperational = isOperational; Error.captureStackTrace(this); } } // 客户端抛出一个异常 if (user == null) throw new AppError(commonErrors.resourceNotFound, commonHTTPErrors.notFound, 'further explanation', true)

TypeScript 版本有两个关键点：

• Object.setPrototypeOf(this, new.target.prototype)：当 TypeScript 将class extends Error编译为 ES5 目标代码时，原生继承会被降级为原型链赋值，导致instanceof Error失效；new.target指向真正被new调用的构造函数，因此这行代码能"恢复原型链"。这也是 TypeScript 官方在支持new.target特性（TS 2.2+）时推荐的写法；
• readonly修饰符：name、httpCode、isOperational一经构造即不可变，防止错误在传递途中被意外篡改，保持状态一致。

五、把 AppError 放入完整的错误处理闭环

单一实践只有在体系中才有战斗力。本仓库的 errorhandling 章节为 AppError 的字段（尤其是isOperational）提供了完整的配套下游，可在你的工程中直接串联：

1. 区分错误类型（operationalvsprogrammererror.md）：isOperational = true表示可预期的操作型错误（如 HTTP 查询失败、参数非法），记日志即可；程序员错误（如读取未定义值）则应尽快重启恢复。
2. 集中式错误处理（centralizedhandling.md）：不要在每个中间件里各自处理错误，而应让错误中间件只负责"捕获并转发"，统一交给一个errorHandler.handleError(error, res)，由它完成日志、监控指标上报（Prometheus、CloudWatch、DataDog、Sentry 等）以及"是否崩溃"的决策。
3. 优雅退出进程（shuttingtheprocess.md）：在process.on('uncaughtException', ...)回调中调用handleError，并通过isTrustedError(error)（本质上检查error.isOperational）决定是否process.exit(1)，再交由 PM2、Forever 等 Restarter 工具以干净状态重启。
4. 兜底捕获未处理的 Promise 拒绝（catchunhandledpromiserejection.md）：由于 Promise 内的throw不会被uncaughtException捕获，应订阅process.on('unhandledRejection', ...)，将reason重新抛出，使其进入统一处理通道。
5. 保证堆栈完整（returningpromises.md）：返回 Promise 前务必显式await，否则 V8 的"零成本异步堆栈"无法保留调用帧，排障时你会看到残缺的 StackTrace。

可以看到，AppError的四个字段（name、httpCode、description、isOperational）分别服务上述不同环节：name用于错误分类展示、httpCode用于向 HTTP 响应映射状态码、description用于可读的日志信息、isOperational用于崩溃决策。这也是为什么本文强调"只需扩展一次"，字段参数化即可覆盖全部场景。

六、业界共识：为什么不多建类型、为什么字符串不是错误

仓库文档收录了数条与"内置 Error 对象"直接相关的业界观点，可作为设计决策的佐证：

"我看不出多建几种类型有什么价值"（Ben Nadel 博客，关键词 "Node.js error object" 排名第 5）：

就我个人而言，我不觉得拥有大量不同类型的错误对象有什么价值（相比之下只保留一种反而更好）——JavaScript 作为一种语言，似乎并不支持基于构造器（Constructor）的错误捕获。因此，基于对象属性做区分，远比基于构造器类型做区分要容易得多。

"字符串不是错误"（devthought.com 博客，关键词排名第 6）：

用字符串代替错误对象，会导致模块之间的互操作性下降，破坏那些可能正在执行instanceof Error检查、或想了解更多错误信息的 API 契约。我们将会看到，在现代 JavaScript 引擎中，除了保存传给构造器的消息之外，错误对象还有非常有趣的属性。

"从 Error 继承并不增加太多价值"（machadogj 博客）：

我对 Error 类的一个顾虑是它并不那么容易扩展。当然，你可以继承它并创建自己的错误类，如 HttpError、DbError 等。但这样做耗时，而且（相比只为 AppError 扩展一次）并不带来太多价值，除非你真的在利用类型做事情。有时你只是想加一条消息并保留内部错误，有时你又想用参数扩展错误，诸如此类。

"Node.js 抛出的所有 JavaScript 与系统错误都继承自 Error"（Node.js 官方文档）：

Node.js 抛出的所有 JavaScript 与系统错误，都继承自或直接是标准 JavaScript Error 类的实例，并且保证至少提供该类上可用的属性。通用的 JavaScript Error 对象并不标明错误发生的具体场景；Error 对象会捕获一个"堆栈追踪"，标明 Error 被实例化时对应的代码位置，并且可能提供错误的文本描述。Node.js 产生的所有错误——包括全部系统错误与 JavaScript 错误——都将是 Error 类的实例或继承自 Error 类。

七、落地清单与小结

把本实践落地到你的 Node.js 项目时，可按如下顺序自查：

1. 全局禁用抛字符串：代码评审中杜绝throw '...'这类写法，统一throw new Error('...')；
2. 只定义一个AppError（JS 用构造器 +Object.create(Error.prototype)，TS 用class extends Error+Object.setPrototypeOf(this, new.target.prototype)），通过name / httpCode / description / isOperational参数区分场景；
3. 为 Error 补充上下文：抛出时带上错误名与 HTTP 状态码，让日志与监控可读、可过滤；
4. 接入统一处理链：结合 centralizedhandling.md、operationalvsprogrammererror.md、shuttingtheprocess.md 与 catchunhandledpromiserejection.md，让每个错误都走同一条"日志 → 监控 → 崩溃决策"流水线；
5. 关注堆栈完整性：async 函数返回 Promise 前显式await（见 returningpromises.md），让 StackTrace 始终包含完整调用帧。

核心结论一句话：Node.js 的错误处理应该"单一基类 + 参数化区分 + 集中式处理"——只扩展内置Error一次得到AppError，用属性而非类型去区分错误，把isOperational交给统一处理器决定是否重启进程。这既保证了代码与第三方库的协议一致，也最大程度保留了 StackTrace 这份最有价值的排障资产。

• 文档
• 教程
• 后端