# @dabh/diagnostics 中文文档

规范地址：https://npmcn.com/package/%40dabh/diagnostics/

版本：2\.0\.9
npm 元数据更新时间：2026-09-07T03:55:18.946Z
中文译文更新时间：2026-11-11T08:17:01.034Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dabh/diagnostics
原文对照：https://npmcn.com/package/%40dabh/diagnostics/?lang=original
项目主页：https://github.com/DABH/diagnostics
源码仓库：https://github.com/DABH/diagnostics

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：31.3 kB，22 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2020-06-22T17:42:34.888Z
- 最新版本发布：2026-09-07T03:55:18.784Z
- 近 30 天下载量：112739843（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 1 个）

## 中文简介

调试您节点.js 模块和事件循环的工具

## 安装

```sh
npm install @dabh/diagnostics
```

也可以使用：`pnpm add @dabh/diagnostics`、`yarn add @dabh/diagnostics`、`bun add @dabh/diagnostics`

## README

# `diagnostics`

## 分发和维修

**达格·哈马舍尔德图书馆** 分配和维护 [DABH 有限责任公司](https://dabh.llc/)。 。 。 . 维修和软件咨询查询: [哈啰@dabh.llc](mailto:hello@dabh.llc)。 。 。 .

这一分布基于Arnout Kazemier的诊断,Martijn Swaagman, 及其贡献者。 原版权通知和麻省理工学院许可证为: 保存在 [自由主义](https://npmcn.com/package/%40dabh/diagnostics/LICENSE)。 。 。 .

在节点.js核心中使用的调试模式演变中的诊断,  
这种极其小而强大的技术最好比作特色 标记为伐木工。 默认已禁用已创建的调试日志, 但可以 启用时不更改代码行,使用旗帜.

-   允许在多个 JavaScript 环境中进行调试, 如节点.js, 浏览器 和反应 - Native.
-   分开开发与生产,以尽量减少对您的影响 捆绑时应用.
-   允许定制日志、信件和更多信息.

![Output Example](https://npmcn.com/package/%40dabh/diagnostics/example.png)

## 安装

模块发布于公共npm注册,可以安装于 运行中 :

```
npm install --save @dabh/diagnostics
```

## 使用量

-   [导言](https://npmcn.com/package/%40dabh/diagnostics/#readme-introduction)
-   [高级用途](https://npmcn.com/package/%40dabh/diagnostics/#readme-advanced-usage)
    -   [生产与发展](https://npmcn.com/package/%40dabh/diagnostics/#readme-production-and-development-builds)
        -   [网络软件包](https://npmcn.com/package/%40dabh/diagnostics/#readme-webpack)
        -   [节点.js](https://npmcn.com/package/%40dabh/diagnostics/#readme-nodejs)
-   [API 密码](https://npmcn.com/package/%40dabh/diagnostics/#readme-api)
    -   [启用](https://npmcn.com/package/%40dabh/diagnostics/#readme-enabled)
    -   [名称空间](https://npmcn.com/package/%40dabh/diagnostics/#readme-namespace)
    -   [. dev/prod (中文(简体) )](https://npmcn.com/package/%40dabh/diagnostics/#readme-devprod)
    -   [设定](https://npmcn.com/package/%40dabh/diagnostics/#readme-set)
    -   [修改](https://npmcn.com/package/%40dabh/diagnostics/#readme-modify)
    -   [使用情况](https://npmcn.com/package/%40dabh/diagnostics/#readme-use)
-   [修改器](https://npmcn.com/package/%40dabh/diagnostics/#readme-modifiers)
    -   [命名空间](https://npmcn.com/package/%40dabh/diagnostics/#readme-namespace-1)
-   [适配器](https://npmcn.com/package/%40dabh/diagnostics/#readme-adapters)
    -   [进程.env](https://npmcn.com/package/%40dabh/diagnostics/#readme-process-env)
    -   [散列轴](https://npmcn.com/package/%40dabh/diagnostics/#readme-hash)
    -   [本地图集](https://npmcn.com/package/%40dabh/diagnostics/#readme-localstorage)
    -   [同步组合](https://npmcn.com/package/%40dabh/diagnostics/#readme-asyncstorage)
-   [盗取者](https://npmcn.com/package/%40dabh/diagnostics/#readme-loggers)

### 导言

简单地创建一个新的日志 `require` 页:1 `@dabh/diagnostics` 模块和调用 返回函数。 它接受两个论点:

1.  `namespace` **需求** 这是您的日志的命名空间 所以我们知道是否有必要 在使用调试旗时启用您的日志。 通常您使用名称为 您的库或应用程序作为第一个根命名空间。 比如说,如果你是 在库中建立解析器( 例如) 您可以设置命名空间 `example:parser`。 。 。 .
2.  `options` 对日志附加配置的对象 . 识别以下密钥:
    -   `force` 强制启用日志机 .
    -   `colors` 默认启用日志的颜色, 但您可以设置此功能 选项到 `false` 来禁用它.

```js
const debug = require('@dabh/diagnostics')('foo:bar:baz');
const debug = require('@dabh/diagnostics')('foo:bar:baz', { options });

debug('this is a log message %s', 'that will only show up when enabled');
debug('that is pretty neat', { log: 'more', data: 1337 });
```

与 `console.log` 在开发过程中添加或删除的语句 使用寿命周期后,您会创建有意义的日志语句,使您深入了解 您正在开发的库或应用程序 .

创建的调试器使用不同的"适应器"来提取调试旗 出自JavaScript环境. 学习如何启用调试旗 在您的特定环境中,单击下面启用的适配器.

-   **浏览器**数字 : [本地图集](https://npmcn.com/package/%40dabh/diagnostics/#readme-localstorage), (中文(简体) ), [散列轴](https://npmcn.com/package/%40dabh/diagnostics/#readme-hash)
-   **节点.js**数字 : [环境变量](https://npmcn.com/package/%40dabh/diagnostics/#readme-processenv)
-   **反应-内在**数字 : [同步组合](https://npmcn.com/package/%40dabh/diagnostics/#readme-asyncstorage)

请注意,返回的日志已全部配置出框, 您 不需要设置任何适配器/修饰器 当您想要对进程进行更先进的控制时。 但如果你想的话 了解更多,阅读下一节.

### 高级用途

有两种具体的使用模式 `diagnostic`, 图书馆开发者 将它作为模块和应用程序开发者的一部分执行 在其应用程序中使用,或者正在寻找使用信件的方法.

使用在其中讨论的简单日志界面 [导言](https://npmcn.com/package/%40dabh/diagnostics/#readme-introduction) 部分,我们让开发者很容易加入到他们的库中 应用、应用和应用 [API 密码](https://npmcn.com/package/%40dabh/diagnostics/#readme-api) 我们允许无限定制 通过允许自定义适配器、记录器和修改器来确保此库 保持相关性。 这些方法不仅允许引入新的伐木机, 但让你在盒子外思考 例如,您可以保存历史 ,并输出未发现的例外情形 您的应用程序所以您有额外的上下文

```js
const diagnostics = require('@dabh/diagnostics');

let index = 0;
const limit = 200;
const history = new Array(limit);

//
// Force all `diagnostic` loggers to be enabled.
//
diagnostics.force = process.env.NODE_ENV === 'prod';
diagnostics.set(function customLogger(meta, message) {
  history[index]= { meta, message, now: Date.now() };
  if (index++ === limit) index = 0;

  //
  // We're running a development build, so output.
  //
  if (meta.dev) console.log.apply(console, message);
});

process.on('uncaughtException', async function (err) {
  await saveErrorToDisk(err, history);
  process.exit(1);
});
```

上面的小片段将保留200个有限的FIFO(First In First Out) 当应用程序崩溃时可以引用的所有调试消息的队列

#### 生产与发展

当你 `require` 页:1 `@dabh/diagnostics` 模块将给您一个日志 优化用于 `development` 这样它就能提供最好的开发者经验 也许吧.

开发记录器可以实现所有 [适配器](https://npmcn.com/package/%40dabh/diagnostics/#readme-adapters) 送给你的 JavaScript 环境, 添加一个将信件输出到 `console.log` 并登记更改信件的功能,这样日志信件会与 提供命名空间, 以便您知道日志消息的来源 .

开发日志没有启用任何适配器、修改器和日志 默认。 这将确保您的日志信息不会意外出现于 生产。 不过这并不意味着无法调试 正在制作中的信息。 你们可以 `force` 要启用的调试器,以及 供应a [自定义日志](https://npmcn.com/package/%40dabh/diagnostics/#readme-loggers)。 。 。 .

```js
const diagnostics = require('@dabh/diagnostics');
const debug = debug('foo:bar', { force: true });

//
// Or enable _every_ diagnostic instance:
//
diagnostics.force = true;
```

##### 网络软件包

WebPack的概念是 [模式](https://webpack.js.org/concepts/mode/#usage)是因为 生成不同的

```js
module.exports = {
  mode: 'development' // 'production'
}
```

当您使用 WebPack CLI 构建您的应用程序时, 您可以使用 `--mode` 旗帜 :

```
webpack --mode=production app.js -o /dist/bundle.js
```

##### 节点.js

当你使用您的应用程序运行时 `Node.js` 你应该 `NODE_ENV` 环境变量改为 `production` 确保您的图书馆 为生产优化进口.

```
NODE_ENV=production node app.js
```

### API 密码

返回的日志显示一些可用于 您的应用程序或库 :

#### 启用

返回的日志将有一个 `.enabled` 分配给它的财产。 这个布尔 可用于检查是否启用了日志 :

```js
const debug = require('@dabh/diagnostics')('foo:bar');

if (debug.enabled) {
  //
  // Do something special
  //
}
```

该财产被曝光为:

-   在伐木机上的财产.
-   元/ 选项对象上的属性 .

#### 名称空间

这是您最初为函数提供的命名空间 .

```js
const debug = require('@dabh/diagnostics')('foo:bar');

console.log(debug.namespace); // foo:bar
```

该财产被曝光为:

-   在伐木机上的财产.
-   元/ 选项对象上的属性 .

#### . dev/prod (中文(简体) )

有不同的建筑物可用 `diagnostics`当你创建一个 使用 `NODE_ENV=production` 你会是 以最优化、较小的 `diagnostics` 以减小你的捆绑大小. 这个 `dev` 财务报告和审定财务报表 `prod` 返回日志上的布尔表示您是否有 生产或开发版的伐木机.

```js
const debug = require('@dabh/diagnostics')('foo:bar');

if (debug.prod) {
  // do stuff
}
```

该财产被曝光为:

-   在伐木机上的财产.
-   元/ 选项对象上的属性 .

#### 设定

设置新日志为默认值 **全部** `diagnostic` 实例。 通过了 参数应该是一个函数,将日志消息写到您曾经在哪里 想要吗? 它收到两个论点:

1.  `meta` 包含所有选项的对象 要写入日志信件的日志以及日志的属性 调试器, 如 `prod`, (中文(简体) ), `dev`, (中文(简体) ), `namespace`, (中文(简体) ), `enabled`。见 [API 密码](https://npmcn.com/package/%40dabh/diagnostics/#readme-api) 页:1 所有暴露的属性.
2.  `args` 需要写入的日志信件数组 .

```js
const debug = require('@dabh/diagnostics')('foo:more:namespaces');

debug.use(function logger(meta, args) {
  console.log(meta);
  console.debug(...args);
});
```

这种方法被曝光为:

-   在伐木机上的方法.
-   元/ 选项对象的方法 .
-   方法 `diagnostics` 模块.

#### 修改

修改方法允许您添加新信件修改器到 **全部** `diagnostic` 实例。 通过的参数应该是一个函数,它会返回过去 修改后的消息。 该函数收到两个参数:

1.  `message`数组,日志信息.
2.  `options`,对象,输入日志时的选项 最初创建.

```js
const debug = require('@dabh/diagnostics')('example:modifiers');

debug.modify(function (message, options) {
  return messages;
});
```

这种方法被曝光为:

-   在伐木机上的方法.
-   元/ 选项对象的方法 .
-   方法 `diagnostics` 模块.

见 [修改](https://npmcn.com/package/%40dabh/diagnostics/#readme-modifiers) 更多信息.

#### 使用情况

添加新内容 `adapter` 改为 **全部** `diagnostic` 实例。 通过的论据 函数返回布尔,以显示是否通过 `namespace` 允许写入日志消息.

```js
const diagnostics = require('@dabh/diagnostics');
const debug = diagnostics('foo:bar');

debug.use(function (namespace) {
  return namespace === 'foo:bar';
});
```

这种方法被曝光为:

-   在伐木机上的方法.
-   元/ 选项对象的方法 .
-   方法 `diagnostics` 模块.

见 [适配器](https://npmcn.com/package/%40dabh/diagnostics/#readme-adapters) 更多信息.

### 修改器

尽可能灵活地改变我们的信息 提出一个概念: `modifiers` 可增强调试消息. 您可以引入您认为重要的功能或细节 对调试消息, 并且不需要我们添加额外的 bloat 到 `diagnostic` 核心键.

例如,您希望信件的前缀为日期 日志消息发生 :

```js
const diagnostics = require('@dabh/diagnostics');

diagnostics.modify(function datetime(args, options) {
  args.unshift(new Date());
  return args;
});
```

现在所有信件都会被前缀为输出的日期 `new Date()`。 。 。 . 以下修改剂随同 `diagnostics` 并启用在 **发展** 仅模式 :

-   [命名空间](https://npmcn.com/package/%40dabh/diagnostics/#readme-namespace)

#### 命名空间

为所有调试实例启用此修改符, 并预缀信件 带有登录名称空间的名称。 名称空间为颜色 使用 `colorspace` 模块,将类似命名空间放在相同的下 色相空间. 您可以为调试器设置多个命名空间 命名空间应当用 `:`

```
foo
foo:bar
foo:bar:baz
```

对于基于控制台的输出 `namespace-ansi` 已使用.

### 适配器

适应器允许 `diagnostics` 来拉 `DEBUG` 财务报告和审定财务报表 `DIAGNOSTICS` 环境 来自不同来源的变量。 并非每个 JavaScript 环境都有 `process.env` 我们可以发挥杠杆作用。 适应器可以让我们有不同的 适用于不同环境的适配器。 意思是你可以写出自己的习惯 适配器,如果需要的话.

这个 `adapter` 函数应该传递一个函数作为参数,这个函数 将接收 `namespace` 作为参数的日志应该返回 a 布尔表示是否启用该日志 .

```js
const debug = require('@dabh/diagnostics')('example:namespace');

debug.adapter(require('@dabh/diagnostics/adapters/localstorage'));
```

修改器只允许 `development`下列适配器为 备有:

#### 进程.env

此适配器启用于 `node.js`。 。 。 .

使用 `DEBUG` 或者说 `DIAGNOSTICS` (两者都被确认)环境变量 以调试旗通过 :

**UNIX/Linux/马克**

```
DEBUG=foo* node index.js
```

在Windows上使用环境变量有点不同,也取决于 您正在使用的工具链 :

**窗口**

```
set DEBUG=foo* & node index.js
```

**动力壳**

```
$env:DEBUG='foo*';node index.js
```

#### 散列轴

此适配器启用于 `browsers`。 。 。 .

此适配器使用 `window.location.hash` 作为环境来源 变量。 它假设散列格式化使用与查询相同的语法 字符串 :

```js
http://example.com/foo/bar#debug=foo*
```

它触发两个 `debug=` 财务报告和审定财务报表 `diagnostics=` 名称.

#### 本地图集

此适配器启用于 `browsers`。 。 。 .

此适配器使用 `localStorage` ,用于存储调试旗的浏览器. 您可以在应用程序代码中设置调试标记, 但您可以 还打开了浏览器WebInspector,并通过控制台启用.

```js
localStorage.setItem('debug', 'foo*');
```

它触发两个 `debug` 财务报告和审定财务报表 `diagnostics` 存储项目。 (请注意) 以小写输入这些密钥)

#### 同步组合

此适配器启用于 `react-native`。 。 。 .

此适配器使用 `AsyncStorage` API 显示于 `react-native` 库以存储并读取 `debug` 或者说 `diagnostics` 存储项目.

```js
import { AsyncStorage } from 'react-native';

AsyncStorage.setItem('debug', 'foo*');
```

与其他适配器不同,这是唯一的适配器是 `async` 所以这意味着 我们无法立即确定 是否应该建立一个日志 启用或禁用。 当日志被创建时 `react-native` 我们刚开始 假设已禁用, 期间发送的任何信件都会被排队 内部.

一旦我们收到数据 `AsyncStorage` API 我们会决定 如果启用了日志, 将队列中的信件冲出并设定 全部 `enabled` 返回的日志中相应的属性.

### 盗取者

默认情况下, 它会记录所有信件到 `console.log` 当日志为时 启用了使用一个适配器设置的调试旗.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40dabh/diagnostics/LICENSE)

## 常见问题

### @dabh/diagnostics 是什么？

调试您节点\.js 模块和事件循环的工具

### 如何安装 @dabh/diagnostics？

在项目目录运行 npm install @dabh/diagnostics，或使用 pnpm add / yarn add / bun add。

### @dabh/diagnostics 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dabh\_\_diagnostics 是否存在。

### @dabh/diagnostics 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dabh/diagnostics 可以商用吗？

@dabh/diagnostics 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dabh/diagnostics 的下载量有多少？

根据 npm 官方下载统计，@dabh/diagnostics 在 2026/10/11 – 2026/11/09 这 30 天内被下载 112,739,843 次，日均约 3,757,995 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dabh/diagnostics 还在维护吗？

最新版本 2\.0\.9 发布于 2026/09/07（2 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 1 个；首次发布于 2020/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。