Node.js 调试指南

 主页   资讯   文章   代码   电子书 

对于 JavaScript 中的 Error，想必大家已经很熟悉了，毕竟天天与它打交道。

Node.js 内置的 Error 类型有：

  1. Error：通用的错误类型，例如：new Error('error!!!')。
  2. SyntaxError：语法错误，例如：require('vm').runInThisContext('binary ! isNotOk')。
  3. ReferenceError：引用错误，如引用一个未定义的变量，例如：doesNotExist。
  4. TypeError：类型错误，例如：require('url').parse(() => {})。
  5. URIError：全局的 URI 处理函数抛出的错误，例如：encodeURI('\uD800')。
  6. AssertError：使用 assert 模块时抛出的错误，例如：assert(false)。

每个 Error 对象通常有 name、message、stack、constructor 等属性。当程序抛出异常时，我们需要根据错误栈（error.stack）定位到出错代码。希望本节能够帮助读者理解并玩转错误栈，写出错误栈清晰的代码，方便调试。

3.3.1 Stack Trace

错误栈本质上就是调用栈（或者叫：堆栈追踪）。所以我们先复习一下 JavaScript 中调用栈的概念。

调用栈：每当有一个函数调用，就会将其压入栈顶，在调用结束的时候再将其从栈顶移出。

来看一段代码：

function c () {
  console.log('c')
  console.trace()
}

function b () {
  console.log('b')
  c()
}

function a () {
  console.log('a')
  b()
}

a()

执行后打印出：

a
b
c
Trace
    at c (/Users/nswbmw/Desktop/test/app.js:3:11)
    at b (/Users/nswbmw/Desktop/test/app.js:8:3)
    at a (/Users/nswbmw/Desktop/test/app.js:13:3)
    at Object.<anonymous> (/Users/nswbmw/Desktop/test/app.js:16:1)
    at ...

可以看出：c 函数中 console.trace() 打印出的堆栈追踪依次为 c、b、a，即 a 调用了 b，b 调用了 c。

稍微修改下上面的例子：

function c () {
  console.log('c')
}

function b () {
  console.log('b')
  c()
  console.trace()
}

function a () {
  console.log('a')
  b()
}

a()

执行后打印出：

a
b
c
Trace
    at b (/Users/nswbmw/Desktop/test/app.js:8:11)
    at a (/Users/nswbmw/Desktop/test/app.js:13:3)
    at Object.<anonymous> (/Users/nswbmw/Desktop/test/app.js:16:1)
    at ...

可以看出：c() 在 console.trace() 之前执行完毕，从栈中移除，所以栈中从上往下为 b、a。

上面示例的代码过于简单，在实际情况下错误栈并没有这么直观。以常用的 mongoose 为例，mongoose 的错误栈并不友好：

const mongoose = require('mongoose')
const Schema = mongoose.Schema
mongoose.connect('mongodb://localhost/test')

const UserSchema = new Schema({
  id: mongoose.Schema.Types.ObjectId
})
const User = mongoose.model('User', UserSchema)
User
  .create({ id: 'xxx' })
  .then(console.log)
  .catch(console.error)

运行后打印出：

{ ValidationError: User validation failed: id: Cast to ObjectID failed for value "xxx" at path "id"
    at ValidationError.inspect (/Users/nswbmw/Desktop/test/node_modules/mongoose/lib/error/validation.js:56:24)
    at ...
  errors:
   { id:
      { CastError: Cast to ObjectID failed for value "xxx" at path "id"
    at new CastError (/Users/nswbmw/Desktop/test/node_modules/mongoose/lib/error/cast.js:27:11)
    at model.$set (/Users/nswbmw/Desktop/test/node_modules/mongoose/lib/document.js:792:7)
    at ...
        message: 'Cast to ObjectID failed for value "xxx" at path "id"',
        name: 'CastError',
        stringValue: '"xxx"',
        kind: 'ObjectID',
        value: 'xxx',
        path: 'id',
        reason: [Object] } },
  _message: 'User validation failed',
  name: 'ValidationError' }

从 mongoose 给出的 error.stack 中看不到任何有用的信息，error.message 告诉我们 "xxx" 不匹配 User 这个 Model 的 id（ObjectID）的类型，其他的字段基本上也是这个结论的补充，却没有给出我们最关心的问题：我写的代码中，到底哪一行出了问题？

如何解决这个问题呢？我们先看看 Error.captureStackTrace 的用法。

3.3.2 Error.captureStackTrace

Error.captureStackTrace 是 V8 提供的一个 API，可以传入两个参数：

Error.captureStackTrace(targetObject[, constructorOpt])

Error.captureStackTrace 会在 targetObject 中添加一个 stack 属性，对该属性进行访问时，将以字符串的形式返回 Error.captureStackTrace() 语句被调用时的代码位置信息（即：调用栈历史）。

举个简单的例子：

const myObject = {}
Error.captureStackTrace(myObject)
console.log(myObject.stack)
// 输出
Error
    at Object.<anonymous> (/Users/nswbmw/Desktop/test/app.js:2:7)
    at ...

除了 targetObject，captureStackTrace 还接收一个类型为 function 的可选参数 constructorOpt，当传递该参数时，调用栈中所有 constructorOpt 函数之上的信息(包括 constructorOpt 函数自身)，都会在访问 targetObject.stack 时被忽略。当需要对终端用户隐藏内部的实现细节时，constructorOpt 参数会很有用。传入第 2 个参数通常用于自定义错误，例如：

function MyError() {
  Error.captureStackTrace(this, MyError)
  this.name = this.constructor.name
  this.message = 'you got MyError'
}

const myError = new MyError()
console.log(myError)
console.log(myError.stack)
// 输出
MyError { name: 'MyError', message: 'you got MyError' }
Error
    at Object.<anonymous> (/Users/nswbmw/Desktop/test/app.js:7:17)
    at ...

如果去掉 captureStackTrace 的第 2 个参数：

function MyError() {
  Error.captureStackTrace(this)
  this.name = this.constructor.name
  this.message = 'you got MyError'
}

const myError = new MyError()
console.log(myError)
console.log(myError.stack)
// 输出
MyError { name: 'MyError', message: 'you got MyError' }
Error
    at new MyError (/Users/nswbmw/Desktop/test/app.js:2:9)
    at Object.<anonymous> (/Users/nswbmw/Desktop/test/app.js:7:17)
    at ...

可以看出：出现了 MyError 相关的调用栈，但我们并不关心 MyError 及其内部是如何实现的。

captureStackTrace 的第 2 个参数可以传入调用链上的其他函数，不一定是当前函数，例如：

const myObj = {}

function c () {
  Error.captureStackTrace(myObj, b)
}

function b () {
  c()
}

function a () {
  b()
}

a()
console.log(myObj.stack)
// 输出
Error
    at a (/Users/nswbmw/Desktop/test/app.js:12:3)
    at Object.<anonymous> (/Users/nswbmw/Desktop/test/app.js:15:1)
    at ...

可以看出：captureStackTrace 的第 2 个参数传入了函数 b，调用栈中隐藏了 b 函数及其以上所有的堆栈帧。

讲到这里，相信读者都明白了 captureStackTrace 的用法。但这具体有什么用呢？其实上面提到了：隐藏内部的实现细节，优化错误栈。

下面以笔者写的一个模块 Mongolass 为例，讲解如何应用 captureStackTrace。

Mongolass 是一个轻量且优雅的连接 MongoDB 的模块。

3.3.3 captureStackTrace 在 Mongolass 中的应用

这里先大体讲讲 Mongolass 的用法。Mongolass 与 Mongoose 类似，有 Model 的概念，Model 上挂载的方法对应对 MongoDB 的 collections 的操作，例如：User.insert。User 是一个 Model 实例，User.insert 方法返回的是一个 Query 实例。Query 的代码如下：

class Query {
  constructor(op, args) {
    Error.captureStackTrace(this, this.constructor);
    ...
  }
}

这里用 Error.captureStackTrace 隐藏了 Query 内部的错误栈细节，但这样带来一个问题：丢失了原来的 error.stack，在 Mongolass 中可以自定义插件，而插件函数的执行是在 Query 内部，假如在插件中抛错，则会丢失相关错误栈信息。

如何弥补呢？Mongolass 的做法是：当 Query 内部抛出错误（error）时，截取有用的 error.stack，然后拼接到 Query 实例通过 Error.captureStackTrace 生成的 stack 上。

来看一段 Mongolass 的代码：

const Mongolass = require('mongolass')
const Schema = Mongolass.Schema
const mongolass = new Mongolass('mongodb://localhost:27017/test')

const UserSchema = new Schema('UserSchema', {
  name: { type: 'string' },
  age: { type: 'number' }
})
const User = mongolass.model('User', UserSchema)

User
  .insertOne({ name: 'nswbmw', age: 'wrong age' })
  .exec()
  .then(console.log)
  .catch(console.error)

运行后打印的错误信息如下：

{ TypeError: ($.age: "wrong age") ✖ (type: number)
    at Model.insertOne (/Users/nswbmw/Desktop/test/node_modules/mongolass/lib/query.js:104:16)
    at Object.<anonymous> (/Users/nswbmw/Desktop/test/app.js:12:4)
    at ...
  validator: 'type',
  actual: 'wrong age',
  expected: { type: 'number' },
  path: '$.age',
  schema: 'UserSchema',
  model: 'User',
  op: 'insertOne',
  args: [ { name: 'nswbmw', age: 'wrong age' } ],
  pluginName: 'MongolassSchema',
  pluginOp: 'beforeInsertOne',
  pluginArgs: [] }

可以看出：app.js 第 12 行的 insertOne 报错，报错原因是 age 字段是字符串 "wrong age"，而我们期望的是 number 类型的值。

3.3.4 Error.prepareStackTrace

V8 暴露了另外一个接口——Error.prepareStackTrace。简单来讲，它的作用就是：定制 stack。用法如下：

Error.prepareStackTrace(error, structuredStackTrace)

第 1 个参数是个 Error 对象，第 2 个参数是一个数组，每一项都是一个 CallSite 对象，包含错误的函数名、行数等信息。对比以下两种代码：

正常的 throw error：

function c () {
  throw new Error('error!!!')
}

function b () {
  c()
}

function a () {
  b()
}

try {
  a()
} catch (e) {
  console.log(e.stack)
}
// 输出
Error: error!!!
    at c (/Users/nswbmw/Desktop/test/app.js:2:9)
    at b (/Users/nswbmw/Desktop/test/app.js:6:3)
    at a (/Users/nswbmw/Desktop/test/app.js:10:3)
    at Object.<anonymous> (/Users/nswbmw/Desktop/test/app.js:14:3)
    at ...

使用 Error.prepareStackTrace 格式化 stack：

Error.prepareStackTrace = function (error, callSites) {
  return error.toString() + '\n' + callSites.map(callSite => {
    return '    -> ' + callSite.getFunctionName() + ' ('
      + callSite.getFileName() + ':'
      + callSite.getLineNumber() + ':'
      + callSite.getColumnNumber() + ')'
  }).join('\n')
}

function c () {
  throw new Error('error!!!')
}

function b () {
  c()
}

function a () {
  b()
}

try {
  a()
} catch (e) {
  console.log(e.stack)
}
// 输出
Error: error!!!
    -> c (/Users/nswbmw/Desktop/test/app.js:11:9)
    -> b (/Users/nswbmw/Desktop/test/app.js:15:3)
    -> a (/Users/nswbmw/Desktop/test/app.js:19:3)
    -> null (/Users/nswbmw/Desktop/test/app.js:23:3)
    -> ...

可以看出：我们自定义了一个 Error.prepareStackTrace 格式化了 stack 并打印出来。

CallSite 对象还有许多 API，例如：getThis、getTypeName、getFunction、getFunctionName、getMethodName、getFileName、getLineNumber、getColumnNumber、getEvalOrigin、isToplevel、isEval、isNative 和 isConstructor，这里不一一介绍了，有兴趣的读者可查看参考链接。

在使用 Error.prepareStackTrace 时需要注意两点：

  1. 这个方法是 V8 暴露出来的，所以只能在基于 V8 的 Node.js 或者 Chrome 里才能使用。
  2. 这个方法会修改全局 Error 的行为。

3.3.5 Error.prepareStackTrace 的其他用法

Error.prepareStackTrace 除了格式化错误栈外还有什么作用呢？sindresorhus 大神还写了一个 callsites 的模块，可以用来获取函数调用相关的信息，例如获取执行该函数所在的文件名：

const callsites = require('callsites')

function getFileName() {
  console.log(callsites()[0].getFileName())
  //=> '/Users/nswbmw/Desktop/test/app.js'
}

getFileName()

我们来看一下源代码：

module.exports = () => {
  const _ = Error.prepareStackTrace
  Error.prepareStackTrace = (_, stack) => stack
  const stack = new Error().stack.slice(1)
  Error.prepareStackTrace = _
  return stack
}

注意以下几点：

  1. 因为修改 Error.prepareStackTrace 会全局生效，所以将原来的 Error.prepareStackTrace 存到一个变量中，函数执行完后再重置回去，避免影响全局的 Error。
  2. Error.prepareStackTrace 函数直接返回 CallSite 对象数组，而不是格式化后的 stack 字符串。
  3. new 一个 Error，stack 是返回的 CallSite 对象数组，因为第 1 项是 callsites，它总是这个模块的 CallSite，所以通过 slice(1) 去掉。

假如我们想获取当前函数的父函数名，则可以这样用：

const callsites = require('callsites')

function b () {
  console.log(callsites()[1].getFunctionName())
  // => 'a'
}

function a () {
  b()
}
a()

3.3.6 Error.stackTraceLimit

Node.js 还暴露了一个 Error.stackTraceLimit 的设置，可以通过设置这个值来改变输出的 stack 的行数，默认值是 10。

3.3.7 Long Stack Trace

stack trace 也有短板，问题出在异步操作上。若在异步回调中抛错，就会丢失绑定回调前的调用栈信息，来看个例子：

const foo = function () {
  throw new Error('error!!!')
}
const bar = function () {
  setTimeout(foo)
}
bar()
// 输出
/Users/nswbmw/Desktop/test/app.js:2
  throw new Error('error!!!')
  ^

Error: error!!!
    at Timeout.foo [as _onTimeout] (/Users/nswbmw/Desktop/test/app.js:2:9)
    at ontimeout (timers.js:469:11)
    at tryOnTimeout (timers.js:304:5)
    at Timer.listOnTimeout (timers.js:264:5)

可以看出：丢失了 bar 的调用栈。

在实际开发过程中，异步回调的例子数不胜数，如果不能知道异步回调之前的触发位置，则会给 debug 带来很大的难度。这时，出现了一个叫 long Stack Trace 的概念。

long Stack Trace 并不是 JavaScript 原生就支持的功能，所以要拥有这样的功能，就需要我们做一些 hack，幸好在 V8 环境下，所有 hack 所需的 API，V8 都已经提供了。

对于异步回调，目前能做的就是在所有会产生异步操作的 API 上做一些手脚，这些 API 包括：

  • setTimeout, setInterval, setImmediate。
  • nextTick, nextDomainTick。
  • EventEmitter.addEventListener。
  • EventEmitter.on。
  • Ajax XHR。

Long Stack Trace 相关的库可以参考：

  1. AndreasMadsen/trace
  2. mattinsler/longjohn
  3. tlrobinson/long-stack-traces

node@8+ 提供了强大的 async_hooks 模块，在本书的后面章节会介绍如何使用。

3.3.8 参考链接

  • https://zhuanlan.zhihu.com/p/25338849
  • https://segmentfault.com/a/1190000007076507
  • https://github.com/v8/v8/wiki/Stack-Trace-API
  • https://www.jianshu.com/p/1d5120ad62bb

上一节：3.2 Async + Await

下一节：3.4 Node@8