Awesome

debug

「一个微小的JavaScript调试工具,以Node.js核心的调试技术为模型. 适用于Node.js和Web浏览器. 」

校对 ✅

翻译的原文	与日期	最新更新	更多
commit	⏰ 2018 7.26		中文翻译

贡献

欢迎 👏 勘误/校对/更新贡献 😊 具体贡献请看

生活

If help, buy me coffee —— 营养跟不上了，给我来瓶营养快线吧! 💰

调试

一个微小的JavaScript调试工具,以Node.js核心的调试技术为模型. 适用于Node.js和Web浏览器.

安装

$ npm install debug

用法

debug导出一个函数; 只需传递模块的名称给函数,它将返回一个装饰了的console.error, 来为您传递调试语句. 这将允许您看出与调试模块的不同部分或者整个模块的调试输出.

例app.js:

var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// 一个假的示例

debug('booting %o', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// 一个假的工作中不同流程

require('./worker');

例worker.js:

var a = require('debug')('worker:a')
  , b = require('debug')('worker:b');

function work() {
  a('doing lots of uninteresting work');
  setTimeout(work, Math.random() * 1000);
}

work();

function workb() {
  b('doing some work');
  setTimeout(workb, Math.random() * 2000);
}

workb();

喔然后用DEBUG环境变量启用它们. 根据空格或逗号分隔的名称

这里有些例子:

Windows命令提示符说明

CMD

在Windows上,使用. 设置环境变量set命令.

set DEBUG=*,-not_this

例:

set DEBUG=* & node app.js

PowerShell (VS Code 默认)

PowerShell使用以下的语法来设置环境变量.

$env:DEBUG = "*,-not_this"

例:

$env:DEBUG='app';node app.js

然后,像往常一样运行要调试的程序.

npm脚本示例:

  "windowsDebug": "@powershell -Command $env:DEBUG='*';node app.js",

命名空间颜色

每个调试实例都根据其空间名称生成颜色. 这有助于可视化解析,可以在调试输出时,识别调试行属于哪个调试实例.

Node.js

在Node.js中,当stderr是TTY时启用颜色. 你也能安装supports-color模块帮助调试,否则调试只会使用少量的基本颜色.

网页浏览器

"Web 调试器"也可以使用颜色来理解%c格式化选项. 这些是WebKit 调试,Firefox (从版本31开始) 和 Firefox的插件 (任何版本) .

毫秒差异

在积极开发应用程序时,查看在一个应用程序运行debug()和下一个之间花费的时间可能很有用. 例如,假设您在请求资源之前调用debug(),"+ NNNms"将显示两次调用之间花费了多少时间.

当 stdout 不是 TTY 时, Date#toISOString()使用,使其更有用于记录调试信息,如下所示:

约定

如果您在一个或多个库中使用它,那么您应该使用库的名称,以便开发人员可以根据需要切换调试,而无需猜测名称. 如果你有多个debug,那么应该使用您的库名称作为前缀,并使用":"分隔不同调试. 例如,来自 Connect 的"bodyParser"将是"connect:bodyParser". 如果在名称的末尾添加"*",则无论 DEBUG环境变量的设置如何,都将始终启用它. 然后,您可以将其用于正常输出以及调试输出.

通配符

该*字符可以用作通配符. 假设您的库具有名为connect:bodyParser,connect:compress,connect:session的调试器,而不是列出所有三个DEBUG=connect:bodyParser,connect:compress,connect:session,你可能只是这样做DEBUG=connect:*,或只需使用DEBUG=*运行一切.

您还可以通过在前面加上 - 字符来排除特定的调试器. 例如,DEBUG=*,-connect:*将包括除connect:之外的所有调试器.

环境变量

在运行Node.js时,您可以设置一些环境变量来改变调试日志记录的行为:

名称	目的
`DEBUG`	启用/禁用特定的调试命名空间.
`DEBUG_HIDE_DATE`	从调试输出中隐藏日期 (非TTY) .
`DEBUG_COLORS`	是否在调试输出中使用颜色.
`DEBUG_DEPTH`	调试深度.
`DEBUG_SHOW_HIDDEN`	显示已检查对象的隐藏属性.

**注意:**环境变量以DEBUG_开头,最终被转换为Options对象，经过%o/%O格式化使用. 请参阅Node.js文档util.inspect()完整列表.

格式化程序

调试使用printf-style格式. 以下是官方支持的格式化程序:

格式化	表示
`%O`	在多行上打印一个对象.
`%o`	在一行上打印一个对象.
`%s`	字符串.
`%d`	数字 (整数和浮点数) .
`%j`	JSON. 替换为字符串'[圆]'如果参数包含循环引用.
`%%`	单个百分号 ('%') . 这不会消耗参数.

自定义格式化程序

您可以扩展自定义格式化程序, 通过添加debug.formatters. 例如,如果您想添加%h来支持 Buffer 作为 hex 进行渲染,你可以这样做:

const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms

浏览器支持

您可以使用构建用于浏览器的脚本,通过使用browserify,或者只是使用browserify-as-a-service build,如果你不想自己建造它.

Debug的启用状态目前已经localStorage持久化. 考虑下面显示的情况worker:a和worker:b,并希望调试两者. 您可以使用此函数localStorage.debug:

localStorage.debug = 'worker:*'

然后刷新页面.

a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);

输出流

默认debug将记录日志在stderr,但是可以通过覆盖它,来为每个命名空间配置log方法:

例stdout.js:

var debug = require('debug');
var error = debug('app:error');

// 默认 使用 stderr 
error('goes to stderr!');

var log = debug('app:log');
// 设置 命名空间 记录日志 通过 console.log
log.log = console.log.bind(console); // 不要忘了绑定 console!
log('goes to stdout');
error('still goes to stderr!');

// 设置所有都通过 console.info 记录
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');

动态设置

您也可以通过调用enable()方法来自我启用调试 :

let debug = require('debug');

console.log(1, debug.enabled('test')); // 没启动

debug.enable('test'); // 启动
console.log(2, debug.enabled('test')); // ok 

debug.disable(); // 关了
console.log(3, debug.enabled('test')); // no

打印:

1 false
2 true
3 false

用法:
enable(namespaces)
namespaces可以包括由冒号和通配符分隔的模式.

注意enable()会完全覆盖 DEBUG 变量 :

$ DEBUG=foo node -e 'var dbg = require("debug"); dbg.enable("bar"); console.log(dbg.enabled("foo"))'
=> false

检查debug目标是否可用

在你创建了debug实例, 你可以通过enabled属性, 来确定调试是否运行了:

const debug = require('debug')('http');

if (debug.enabled) {
  // do stuff...
}

当然,您还可以手动切换此属性以强制启用或禁用调试实例.

作者

TJ Holowaychuk
Nathan Rajlich
Andrew Rhyne

支持者

Support us with a monthly donation and help us continue our activities🥄 [Become a backer]

赞助商

Become a sponsor and get your logo on our README on Github with a link to your site🥄 [Become a sponsor]

License

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT🥄 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

</details>