一、console.dir()的本质：util.inspect()的格式化输出封装

console.dir()的官方定义只有一句话：对obj使用util.inspect()，将结果字符串打印到stdout。

这意味着console.dir()不是一个独立的检视引擎，而是util.inspect()的输出管道。理解这个委托关系是掌握console.dir()行为边界的前提。util.inspect()是Node.js的核心对象格式化工具，负责将任意JavaScript值转换为可读字符串。console.dir()的职责是将这个字符串写入标准输出流。

语法为：

console.dir(obj[, options])

obj可以是任意JavaScript值——对象、数组、函数、原始值。options是可选的配置对象，所有属性原样传递给util.inspect()。

官方文档明确标注了一个容易被忽视的语义：console.dir()绕过obj上定义的任何custominspect()函数。这与console.log()的行为形成对照——console.log()在格式化对象时会调用util.inspect()，而后者会尊重对象自定义的[util.inspect.custom]方法。console.dir()的绕过设计意味着：无论对象如何“伪装”自己的打印输出，console.dir()都会强制展示其真实属性结构。

二、options参数体系：depth、showHidden与colors

console.dir()的灵活性全部来自options对象。以下三个选项在调试中具有实际价值。

depth控制递归层级。默认值为2，意味着嵌套超过两层的对象会被折叠为[Object]或[Array]。在调试深层嵌套的配置对象时，这个默认值几乎总是需要调整的。传入null表示无限递归。

// 使用代码号学习编程的场景：检视多层嵌套的配置
const appConfig = {
  server: {
    http: {
      port: 8080,
      timeout: 30000,
      headers: {
        'x-custom': 'value',
        'x-trace': true
      }
    }
  }
};

console.dir(appConfig);                    // 默认 depth:2，headers 被折叠
console.dir(appConfig, { depth: null });   // 完整展开所有层级

showHidden控制是否显示不可枚举属性和Symbol属性。默认false。在检视类实例时，原型链上的方法通常不可枚举，默认不会显示。需要查看类实例的完整方法列表时，将其设为true。

colors控制ANSI颜色输出。在Node.js的早期文档中，colors的默认值为true，但后续版本的MDN文档将其标注为默认true，实际行为依赖终端能力。在CI日志采集或管道输出场景中，强制关闭colors可以避免ANSI转义序列污染日志文件。

三、与console.log()的行为分歧

console.dir()和console.log()都使用util.inspect()来格式化对象，但存在两个关键差异。

第一，customInspect的尊重与否。console.log()在遇到自定义了[util.inspect.custom]方法的对象时，会调用该方法来决定输出内容。console.dir()则绕过这个自定义方法，强制展示对象的原始属性。

这个差异在调试中很重要。许多库（如Chalk、Mongoose文档）会为对象定义自定义检视方法，让日志输出更简洁。当你需要“看穿”这些伪装、检查对象的真实内部状态时，console.dir()是更可靠的选择。

第二，多参数处理。console.log()支持printf风格的多参数格式化，第一个参数中的%s、%d会被后续参数替换。console.dir()只接受一个被检视对象，options作为第二个参数。试图用console.dir('value:%d',42)不会得到格式化替换，'value:%d'本身会被当作待检视的字符串值。

四、循环引用的处理机制

循环引用是对象检视中的经典问题。一个对象直接或间接引用自身时，朴素递归会无限循环。

util.inspect()（以及委托它的console.dir()）自动检测循环引用，在输出中用[Circular]标记重复出现的对象引用。这并非console.dir()独有的能力——console.log()在格式化对象时同样享受这个保护。但理解这一机制对于解读输出很重要：当你看到[Circular]时，说明该位置的对象已经在检视路径中出现过，util.inspect()选择了截断而非继续递归。

const node = { id: 1 };
node.next = node;
console.dir(node, { depth: null });
// 输出：{ id: 1, next: [Circular] }

这个行为与JSON.stringify()形成鲜明对比。JSON.stringify()遇到循环引用会抛出TypeError:CortingcircularstructuretoJSON。在调试时，如果对象可能包含循环引用，console.dir()比JSON.stringify()更安全。

五、单元测试方案

console.dir()的测试难点在于它直接写入全局process.stdout，且util.inspect()的输出格式在不同Node版本间可能存在细微差异。以下测试策略基于自定义Console实例，避免污染全局输出。

测试一：验证输出包含对象属性

const test = require('node:test');
const assert = require('node:assert');
const { Console } = require('node:console');
const { Writable } = require('node:stream');

function captureDir(obj, options) {
  const chunks = [];
  const stream = new Writable({
    write(chunk, enc, cb) { chunks.push(chunk.toString()); cb(); }
  });
  const c = new Console(stream);
  c.dir(obj, options);
  return chunks.join('');
}

test('console.dir 输出对象属性名', () => {
  const output = captureDir({ name: 'test', value: 42 });
  assert.match(output, /name/);
  assert.match(output, /value/);
  assert.match(output, /42/);
});

测试二：depth选项的截断行为

test('depth:1 时深层对象被折叠', () => {
  const nested = { a: { b: { c: 1 } } };
  const output = captureDir(nested, { depth: 1 });
  assert.match(output, /\[Object\]/);
});

测试三：边界——对原始值调用dir

test('console.dir 对原始值不抛错', () => {
  assert.doesNotThrow(() => captureDir('hello'));
  assert.doesNotThrow(() => captureDir(42));
  assert.doesNotThrow(() => captureDir(null));
});

需要说明的是，这些测试验证的是“输出包含预期内容”，而非“输出格式匹配某版本”。util.inspect()的输出格式在Node.js主版本间可能变化，断言不应过度依赖精确字符串匹配。

六、常见误区速查

误区	实际行为
认为console.dir是console.log的别名	console.dir绕过customInspect，console.log尊重它
在console.dir中使用%d、%s格式化	不支持printf风格，第一个参数始终被检视
认为默认depth是null	默认depth为2，深层对象被折叠为[Object]
用JSON.stringify替代console.dir调试循环引用	console.dir用[Circular]处理，JSON.stringify抛错
在管道输出中期望看到颜色	颜色依赖TTY能力，非TTY环境下默认关闭或有限支持
认为console.dir的输出可被assert直接捕获	输出写入stdout流，需要自定义Console或mock才能捕获

七、场景

7.1模块导出检视

在调试“某个require返回了什么”时，console.dir()比console.log()更可靠，因为模块导出对象可能定义了自定义检视方法。

const someModule = require('./some-module');
console.dir(someModule, { depth: 1, colors: false });

7.2配置对象的完整展开

多层嵌套的配置对象是console.dir()的典型用武之地。depth:null配合colors:false适合将完整配置写入日志文件进行事后分析。

console.dir(config, { depth: null, colors: false });

7.3调试框架中的使用

一个来自GitHub的真实问题展示了console.dir在测试mock中的：某项目的sayHi函数内部使用console.dir()输出，而单元测试mock的是console.log，导致测试无法捕获到预期的输出。这个案例说明：测试中mockconsole时，必须确认被mock的方法与实际调用的方法一致。console.dir和console.log是不同的方法，不会互相覆盖。

八、练习与思考

练习一：以下代码的输出中，inner属性会显示什么？

const obj = { a: { b: { c: { d: 1 } } } };
console.dir(obj);

练习二：写一个函数safeDir(obj)，先检测对象是否包含循环引用，若包含则使用console.dir(obj,{depth:null})输出，否则使用console.log(JSON.stringify(obj,null,2))。这个函数在什么场景下有意义？

思考：console.dir()绕过customInspect的设计，在调试第三方库对象时带来便利，但在日常日志输出中可能造成信息过载。你会在什么条件下选择console.dir而非console.log？

延伸阅读与参考文献

Node.js 官方文档-console.dir(obj[,options])
https://nodejs.org/api/console.html#consoledirobjoptions
定义了console.dir()对util.inspect()的委托关系，以及showHidden、depth、colors三个选项的语义。同时明确标注了“绕过obj上定义的custominspect函数”的关键行为。

Node.js 官方文档-util.inspect()
https://nodejs.org/api/util.html#utilinspectobject-options
console.dir()格式化能力的底层来源。depth的默认值、colors的ANSI实现、showHidden对不可枚举属性的处理，均在此定义。

MDN Web Docs-console.dir()
https://developer.mozilla.org/en-US/docs/Web/API/console/dir_static
浏览器端与Node.js端的对比说明，明确指出options参数在Node等非交互式终端环境中的定制作用，以及depth默认值为2的规范。

WHATWG Console Issue #79-Node.js的options参数与规范差异
https://github.com/whatwg/console/issues/79
记录了console.dir()的options参数作为Node.js特有扩展进入WHATWG规范讨论的过程。浏览器实现不强制支持options，但忽略该参数仍符合规范。

Stack Overflow-How can I get the full object in Node.js'sconsole.log()
https://stackoverflow.com/questions/10729276/
高票回答的更新时间线显示，2012年时console.log深层对象会显示[Object]，而console.dir(obj,{depth:null})已成为当前推荐方案。该讨论的演变本身反映了Node.js对象检视能力的提升轨迹。

kidnap-console-console 输出捕获工具
https://www.npmjs.com/package/kidnap-console
展示了在单元测试中捕获console.dir、console.log、console.warn输出的实际方案，是测试console.dir调用行为时的参考实现。