stacktrace.js 技术文档

1. 安装指南

通过 npm 安装

npm install stacktrace-js

通过 Bower 安装

bower install stacktrace-js

通过 Component 安装

component install stacktracejs/stacktrace.js

通过 CDN 引入

<script src="http://cdnjs.com/libraries/stacktrace.js"></script>

2. 项目的使用说明

获取当前位置的堆栈跟踪

var callback = function(stackframes) {
    var stringifiedStack = stackframes.map(function(sf) {
        return sf.toString();
    }).join('\n');
    console.log(stringifiedStack);
};

var errback = function(err) { console.log(err.message); };

StackTrace.get().then(callback).catch(errback);

同步获取堆栈跟踪

StackTrace.getSync();

与 window.onerror 集成

window.onerror = function(msg, file, line, col, error) {
    StackTrace.fromError(error).then(callback).catch(errback);
};

从错误对象获取堆栈跟踪

var error = new Error('BOOM!');
StackTrace.fromError(error).then(callback).catch(errback);

人工生成堆栈跟踪

StackTrace.generateArtificially().then(callback).catch(errback);

跟踪函数的每次调用

var myFunc = function(arg) { return 'Hello ' + arg; };
var myWrappedFunc = StackTrace.instrument(myFunc, callback, errback);
myWrappedFunc('world');

3. 项目API使用文档

StackTrace.get(options)

生成从调用点开始的堆栈跟踪，并解析和增强它。

参数：

• options（可选）：包含以下选项的对象：
  • filter：过滤函数，只包含返回 true 的堆栈条目。
  • sourceCache：预填充的源缓存，避免网络请求。
  • offline：布尔值，设置为 true 以防止所有网络请求。

返回值：

• 返回一个 Promise，解析为 StackFrame 数组。

StackTrace.getSync(options)

生成从调用点开始的堆栈跟踪，并解析它。此方法不使用源映射或猜测匿名函数名称。

参数：

• options（可选）：包含以下选项的对象：
  • filter：过滤函数，只包含返回 true 的堆栈条目。

返回值：

• 返回一个 StackFrame 数组。

StackTrace.fromError(error, options)

给定一个 Error 对象，使用 error-stack-parser 解析它，并使用 stacktrace-gps 增强位置信息。

参数：

• error：Error 对象。
• options（可选）：包含以下选项的对象：
  • filter：过滤函数，只包含返回 true 的堆栈条目。
  • sourceCache：预填充的源缓存，避免网络请求。
  • offline：布尔值，设置为 true 以防止所有网络请求。

返回值：

• 返回一个 Promise，解析为 StackFrame 数组。

StackTrace.generateArtificially(options)

通过遍历 arguments.callee.caller 链生成堆栈跟踪。

参数：

• options（可选）：包含以下选项的对象：
  • filter：过滤函数，只包含返回 true 的堆栈条目。
  • sourceCache：预填充的源缓存，避免网络请求。
  • offline：布尔值，设置为 true 以防止所有网络请求。

返回值：

• 返回一个 Promise，解析为 StackFrame 数组。

StackTrace.instrument(fn, callback, errback)

给定一个函数，包装它以便在调用时触发回调，回调函数将接收一个堆栈跟踪。

参数：

• fn：要包装的函数。
• callback：在调用 fn 时触发的回调函数，接收堆栈跟踪。
• errback（可选）：如果获取堆栈跟踪时发生错误，将调用此函数。

返回值：

• 返回一个包装后的函数。

StackTrace.deinstrument(fn)

给定一个已被包装的函数，将其恢复为原始状态。

参数：

• fn：已被包装的函数。

返回值：

• 返回原始函数。

StackTrace.report(stackframes, url, message, requestOptions)

给定一个错误消息和 StackFrame 数组，序列化并 POST 到给定的 URL。

参数：

• stackframes：StackFrame 数组。
• url：POST 请求的目标 URL。
• message：错误消息。
• requestOptions：HTTP 请求选项对象，仅支持 headers。

返回值：

• 返回一个 Promise，解析为 POST 请求的响应文本。

4. 项目安装方式

通过 npm 安装

npm install stacktrace-js

通过 Bower 安装

bower install stacktrace-js

通过 Component 安装

component install stacktracejs/stacktrace.js

通过 CDN 引入

<script src="http://cdnjs.com/libraries/stacktrace.js"></script>