Node.js 中的 report 模块是用于生成诊断报告的工具。这些报告包含了程序当前的状态、调用栈、系统信息、加载的模块等内容，能够帮助开发者在调试和分析 Node.js 应用程序的运行问题时使用。

诊断报告可以通过程序运行时自动生成，也可以手动触发。它们对故障排查、性能调优、内存泄漏检测等问题非常有帮助。

1. Report 模块概述

report 模块用于生成诊断报告，包含应用程序的运行状态、JavaScript 堆信息、操作系统状态等详细内容。这些报告帮助开发者了解应用在发生崩溃或性能问题时的具体情况。

诊断报告的核心功能包括：

• 生成报告的文件路径和格式定制。
• 在崩溃、未捕获的异常或信号等情况下自动生成报告。
• 手动生成报告。
• 通过环境变量配置自动生成报告的行为。

在 Node.js v12.0.0 中，report 功能被引入作为实验性功能，在 v13.9.0 及之后成为稳定功能。

2. Report 的属性与方法

2.1 process.report.getReport()

process.report.getReport() 方法返回当前程序的诊断报告。返回值为一个包含报告内容的字符串（JSON 格式）。这个方法不会写入文件，而是将报告直接返回。

语法：

const report = process.report.getReport();
console.log(report);

示例：

const report = process.report.getReport();
console.log("生成的报告内容：", report);

这个方法适用于你希望即时获取程序状态并在代码中处理报告内容的场景。

2.2 process.report.writeReport()

process.report.writeReport() 用于将诊断报告写入文件。可以通过提供文件路径来指定报告的保存位置，如果不提供路径，报告将保存到默认目录下。

语法：

process.report.writeReport([filename]);

• filename: 可选，生成报告的文件名。如果未指定，则按照默认格式生成文件名。

示例：

const filename = process.report.writeReport();
console.log(`报告已生成并保存到 ${filename}`);

你也可以手动指定文件路径：

process.report.writeReport('/tmp/my-node-report.json');

这个方法适用于希望将报告保存为文件的场景，以便于之后分析。

2.3 process.report.directory

process.report.directory 属性允许你获取或设置生成报告文件的默认目录。如果未设置，报告将保存到当前工作目录。

语法：

console.log(process.report.directory); // 获取当前默认目录
process.report.directory = '/path/to/directory'; // 设置默认目录

示例：

process.report.directory = '/var/logs';
process.report.writeReport();

报告文件会保存到 /var/logs 目录中。

2.4 process.report.filename

process.report.filename 是一个只读属性，它返回最后生成的报告的文件名（包括路径）。

语法：

console.log(process.report.filename);

示例：

process.report.writeReport();
console.log(`报告文件名为：${process.report.filename}`);

2.5 process.report.triggerReport()

process.report.triggerReport() 方法用于在代码中手动触发诊断报告生成。它通常用于希望在特定条件下生成报告的情况，比如内存使用异常或应用性能下降时。

语法：

process.report.triggerReport();

这个方法会根据配置或默认设置，将报告生成到文件或控制台。

示例：

if (process.memoryUsage().heapUsed > 100 * 1024 * 1024) {
  process.report.triggerReport();
}

当内存使用超过 100 MB 时，自动触发生成诊断报告。

2.6 process.report.signal

process.report.signal 属性允许你设置一个信号，当该信号发送到当前进程时会触发诊断报告生成。常见的信号包括 SIGUSR2。

语法：

process.report.signal = 'SIGUSR2';

示例：

process.report.signal = 'SIGUSR2';

// 现在发送 `SIGUSR2` 信号将会触发报告生成

设置后，通过系统向 Node.js 进程发送 SIGUSR2 信号即可生成报告。这在需要通过外部手段触发报告时非常有用。

3. 诊断报告触发方式

生成诊断报告有多种方式：

1. 手动触发：通过 process.report.writeReport() 或 process.report.triggerReport() 手动生成报告。
2. 信号触发：配置 process.report.signal，当接收到特定信号时生成报告。
3. 崩溃自动生成：当未捕获的异常或致命错误发生时，自动生成报告。
4. 环境变量触发：通过设置环境变量 NODE_OPTIONS=--report-uncaught-exception 或 NODE_OPTIONS=--report-on-fatalerror，当程序出现未捕获异常或致命错误时自动生成报告。

4. 使用场景与示例

场景 1：调试内存泄漏问题

假设应用程序在运行过程中内存不断增加，开发者可以通过 process.report.triggerReport() 在内存使用超出某个阈值时自动生成报告，用于后续的内存泄漏分析。

if (process.memoryUsage().heapUsed > 200 * 1024 * 1024) {
  console.log('内存使用超出 200MB，生成诊断报告...');
  process.report.writeReport('/tmp/memory-report.json');
}

场景 2：未捕获异常导致崩溃时生成报告

通过设置 NODE_OPTIONS 环境变量，可以确保在应用程序出现未捕获异常时自动生成诊断报告。

export NODE_OPTIONS="--report-uncaught-exception"
node app.js

这样当 app.js 出现未捕获异常时，诊断报告会自动生成。

场景 3：信号触发诊断报告

在系统中，你可以通过信号的方式触发报告生成，这特别适用于长期运行的服务。配置 SIGUSR2 信号生成报告：

process.report.signal = 'SIGUSR2';

运行服务时，使用命令发送信号：

kill -SIGUSR2 <node_pid>

此时会生成报告，保存至配置的目录中。

5. 总结

Node.js 的 report 模块是一个强大的调试工具，它提供了详细的诊断信息，帮助开发者排查问题。开发者可以通过手动或自动触发的方式生成报告，报告中包含系统状态、进程信息、调用栈等细节。这些报告非常适合用于解决崩溃问题、性能瓶颈以及内存泄漏等问题。

使用诊断报告，可以快速收集应用崩溃时的详细信息，从而缩短排查问题的时间。在生产环境中，通过信号触发或自动生成报告可以极大提高问题的可追踪性。