Playwright Logger 详解：可插拔日志 Sink、isEnabled/log 契约与源码级日志链路分析

本文以 Playwright 官方 API 文档 class-logger.md 为主体，完整梳理 Logger 可插拔日志类的设计契约：isEnabled / log 两个回调方法的参数语义、四种日志级别、挂载入口与最小可用示例；并结合 playwright-core 源码 还原 API 调用日志、协议日志与通道调试日志三条链路的真实实现，最后说明该类的废弃状态与推荐的 tracing 替代方案。读完本文，你将能够为自己的脚本或测试框架接入自定义日志 Sink，理解每条日志从客户端到服务端的产生路径，并判断何时该切换到 Trace Viewer。

1. Logger 是什么：一个可插拔的日志 Sink

Playwright 内部会产生大量日志（API 调用、协议消息等），Logger 类（自 v1.8 引入，仅支持 JavaScript API）就是这些日志对外的统一出口：用户提供一个“Sink”（日志汇），Playwright 在合适的时机回调它，由用户决定记录到哪里、以什么格式记录。

官方文档中的最小完整示例如下：

const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.

(async () => {
  const browser = await chromium.launch({
    logger: {
      isEnabled: (name, severity) => name === 'api',
      log: (name, severity, message, args) => console.log(`${name} ${message}`)
    }
  });
  // ...
})();

这个例子展示了典型用法：isEnabled 做预过滤（只关心名为 api 的日志源），log 做实际输出。这种“先问要不要、再给日志”的两段式契约，避免了被过滤掉的日志仍要构造字符串的开销——这一点在源码中能得到印证，后文会具体展开。

重要提示（来自原文档的废弃声明）：该文档明确标注 This class is deprecated. The logs pumped through this class are incomplete. Please use tracing instead. 即通过 Logger 输出的日志是不完整的，官方推荐改用 tracing（详见 Trace Viewer 入门）。Logger 仍可用于轻量调试场景，但新项目中建议以 trace 作为排障主手段。

2. Logger 接口完整契约

Logger 是一个对象类型，由两个方法组成，对应 types.d.ts 中的接口定义：

export interface Logger {
  isEnabled(name: string, severity: "verbose"|"info"|"warning"|"error"): boolean;

  log(
    name: string,
    severity: "verbose"|"info"|"warning"|"error",
    message: string|Error,
    args: ReadonlyArray<Object>,
    hints: { color?: string }
  ): void;
}

2.1 method: Logger.isEnabled(name, severity)

判断当前 Sink 是否“感兴趣”某个指定名字与级别的日志源，返回 boolean。这是所有日志输出前的守门员。

参数	类型	说明
name	string	日志源名字，例如 api、protocol
severity	"verbose" | "info" | "warning" | "error"	日志级别，四级递进

2.2 method: Logger.log(name, severity, message, args, hints)

当 isEnabled 返回 true 后，Playwright 通过该方法投递具体日志。

参数	类型	说明
name	string	日志源名字，与 isEnabled 中的 name 对应
severity	"verbose" | "info" | "warning" | "error"	日志级别
message	string | Error	日志消息本体（可以是字符串或 Error 对象）
args	Array<Object>	消息的参数数组
hints	Object	可选的格式提示，含 color?: string（建议的日志展示颜色）

其中 hints.color 是一个“建议值”而非强制值：从源码可以确认，Playwright 在打 API 调用日志时会显式传入 { color: 'cyan' }（见 channelOwner.ts），Sink 可以据此为自己的终端着色。

3. 挂载入口：logger 参数在哪里生效

logger 作为选项字段出现在多个与连接/启动相关的配置对象中，types.d.ts 中该字段的注释统一为 “Logger sink for Playwright logging”，覆盖的主要入口包括：

• browserType.launch({ logger }) —— 最典型的挂载点，如第 1 节示例；
• browserType.launchServer({ logger })；
• browserType.connect({ logger }) 等远程连接入口。

客户端 Browser 类通过类型导入接收该配置（见 browser.ts 中 LaunchOptions, Logger 的引入），并在启动浏览器服务器时向下传递。

4. 源码级链路分析：日志从哪里来

Logger 文档本身只约定了“谁调用你”，而“谁在调用你、调用时传什么”需要在源码中回答。结合 playwright-core 源码 可以确认三条主要日志链路。

4.1 API 调用日志：api 源，info 级别

每次客户端 API 调用（如 page.click()、page.goto()）都会在 ChannelOwner 中经过统一的 RPC 分发路径，调用结束（含失败）时触发日志：

// packages/playwright-core/src/client/channelOwner.ts
private ... {
  if (!options?.internal) {
    apiZone.error = e;
    logApiCall(logger, `<= ${apiZone.apiName} failed`);
    this._instrumentation.onApiCallEnd(apiZone);
  }
  throw e;
}
// ...
function logApiCall(logger: Logger | undefined, message: string) {
  if (logger && logger.isEnabled('api', 'info'))
    logger.log('api', 'info', message, [], { color: 'cyan' });
  debugLogger.log('api', message);
}

见 channelOwner.ts#L215-L242。可以从中读出三个实现要点：

1. 先问再写：先调用 logger.isEnabled('api', 'info')，为 true 才真正 log，印证了第 2 节描述的预过滤契约；
2. api 源记录每次 API 调用的开始与结束，消息形如 <= page.click failed（前缀 <= 表示调用返回），内部调用（options.internal）会被跳过；
3. 双轨并行：同一条日志还会写入内置的 debugLogger（见 4.3 节），两条轨道互不依赖。

这也解释了文档示例中 isEnabled: (name) => name === 'api' 的过滤写法——它正是针对这条最常用的日志链路。

4.2 协议日志：protocol 源，verbose 级别

当启动浏览器服务器时，用户传入的 logger 会被适配为协议层日志器，记录客户端与浏览器之间每一条消息的收发：

// packages/playwright-core/src/browserServerImpl.ts
function toProtocolLogger(logger: Logger | undefined): ProtocolLogger | undefined {
  return logger ? (direction: 'send' | 'receive', message: object) => {
    if (logger.isEnabled('protocol', 'verbose'))
      logger.log('protocol', 'verbose',
        (direction === 'send' ? 'SEND ► ' : '◀ RECV ') + JSON.stringify(message), [], {});
  } : undefined;
}

见 browserServerImpl.ts#L104-L109。要点：

• 协议日志使用 verbose 级别，是四个级别中最细粒度的，且只在此处使用 verbose；如果你的 isEnabled 对 verbose 返回 false，整个协议流量就完全静默；
• 每条消息以 SEND ► / ◀ RECV 前缀区分方向，内容是完整的 JSON 消息体——这也是它信息量最大、同时最“吵”的原因；
• 由于消息体完整序列化，协议日志量很大，实践中通常只在排查特定连接问题时开启。

4.3 第三轨道：内置 debugLogger 与 DEBUG 环境变量

除了用户 Sink，Playwright 还内置了一条基于 debug 包的日志轨道，见 packages/utils/debugLogger.ts。从源码结构看：

• 每个日志源映射到 pw:<name> 命名空间（如 pw:api、pw:protocol、pw:channel），因此设置 DEBUG='pw:api' 或 DEBUG='pw:*' 即可在终端查看对应日志；
• 内置颜色表定义了各日志源的终端配色（api 为青色、protocol 为绿色、channel 为蓝色等），与 hints.color 的建议语义相呼应；
• 设置 DEBUG_FILE 环境变量后，日志会被剥离 ANSI 转义并追加写入文件，便于离线分析；
• 通道级调试日志（RPC 消息的 SEND> / <RECV / <EVENT）走的是这条轨道而非用户 Sink，见 connection.ts#L196-L199 中对 debugLogger.isEnabled('channel') 的判断。

换言之：用户 Logger Sink 主要接收 api 与 protocol 两类日志，而更底层的 channel、server 等日志通过 DEBUG 环境变量开启。这解释了文档中“logs pumped through this class are incomplete”的废弃声明——用户 Sink 看不到全部内部日志，完整视图需要依赖 tracing。

5. 一个更完整的 Sink 示例

综合以上分析，可以写一个按级别与来源分流的 Sink，作为可复制的参考实现：

const { chromium } = require('playwright');

const logger = {
  // 预过滤：api 全级别接收；protocol 仅接收 verbose（协议流量大，按需开启）
  isEnabled: (name, severity) => {
    if (name === 'api') return true;
    if (name === 'protocol') return process.env.LOG_PROTOCOL === '1';
    return false;
  },
  log: (name, severity, message, args, hints) => {
    // message 可能是 string 也可能是 Error
    const text = message instanceof Error ? message.stack : message;
    // hints.color 只是建议值，是否使用取决于自己的输出端
    console.error(`[${severity}] ${name}: ${text}`);
  },
};

(async () => {
  const browser = await chromium.launch({ logger });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

要点回顾：isEnabled 返回 false 时对应的日志根本不会构造和投递；message 需要兼容 string | Error 两种类型；hints.color 为可选建议项。

6. 验证与替代方案

• 测试依据：仓库内置的 tests/library/logger.spec.ts 即针对该功能的端到端测试，可将其作为 Logger 行为边界的参考用例；
• 废弃后的替代方案：文档明确指出该类已废弃，原因是经 Sink 输出的日志不完整。排查行为问题（页面动作时序、网络请求、DOM 快照等）的官方推荐路径是 tracing + Trace Viewer，相关文档见 trace-viewer.md 与 trace-viewer-intro-js.md。Logger 的合理定位因此收窄为：轻量脚本中对 API 调用与协议流量的实时打印，而非完整的调试工具。

7. 小结

• Logger（v1.8+，JS 专属，已标记 deprecated）是 Playwright 的可插拔日志 Sink，契约为 isEnabled(name, severity) 预过滤 + log(name, severity, message, args, hints) 投递；
• 四个级别 verbose | info | warning | error 中，源码确认的实际使用点为：api 源用 info（channelOwner.ts#L238-L242），protocol 源用 verbose（browserServerImpl.ts#L104-L109）；
• 更底层的 channel/server 等日志不经过用户 Sink，需通过 DEBUG='pw:*' 环境变量查看（packages/utils/debugLogger.ts）；
• 新场景下优先使用 tracing；需要理解日志产生机制或维护旧脚本时，本文的接口契约与源码链路可直接作为参照。