debug-web

v2.4.0

Published

2 months ago

Browser debug utility with console styling and persistent levels (ES2018+)

0High
0Medium
0Low

ll.karlen

browser console debug level web log logging debugging typescript

Debug Web

用于浏览器调试的 NPM 包，具有可自定义的日志级别（log、warn、error、debug）。
轻量且易于使用。

特点:

无依赖 — 纯 TypeScript 编写；
体积 ~3.5 kB — 对打包体积影响极小；
SonarQube A 评级 — 最高级别的代码质量和可靠性；
控制台输出样式 — 彩色格式化，便于快速识别；
全局存储 — 通过 window 访问调试数据；
灵活配置 — 支持日志级别、样式、别名及继承。

翻译版本

English, Español, Deutsch, 中文, Русский

安装

npm install debug-web

yarn add debug-web

日志级别

优先级（从低到高）：

debug (0) — 调试信息 (console.debug);
log (1) — 基础消息 (console.log)
info (2) — 提示信息 (console.info)
warn (3) — 警告 (console.warn)
error (4) — 错误 (console.error)

ℹ️ 自定义级别：任何字符串值（例如 success、focus）将按特定方式处理：

常规自定义级别（不带下划线前缀）使用 info 级别
以下划线开头的级别（例如 _info、_error）使用 debug 级别两者都可以有自己的样式。

选项

| 参数 | 类型 | 默认值 | 描述 | |----------|---------------------------------|---------------|-------------------------------------------------| | app | string | null | 'debug' | 唯一的应用程序名称，用于分离数据 | | level | DebugLogLevel | 'log' | 最低日志级别（低于此级别的消息将不会输出） | | prop | string | null | 'debug' | 用于访问数据的全局变量名（null — 不创建） | | data | Record<string, unknown> | undefined | 初始调试数据 | | local | boolean | false | 将级别保存在 localStorage 中（否则保存在 sessionStorage） | | native | boolean | false | 使用原生控制台方法（不带样式） | | onLog | (level, attrs) => void | undefined | 每次日志记录后调用的函数 | | title | Record<string, string> | undefined | 自定义日志级别的标题 | | alias | Record<string, DebugLogLevel> | 见下方 | createDebug 的自定义别名 | | style | Record<DebugLogLevel, string> | 见下方 | 日志级别的 CSS 样式 |

type DebugLogLevel = 'debug' | 'log' | 'info' | 'success' | 'warn' | 'error' | string;

默认样式

| 级别 | 样式 (CSS) | |-----------|----------------------------------------------------------------------------| | info | background-color: #155adc; color: #fff; padding: 2px; border-radius: 3px | | mark | background-color: #695aff; color: #fff; padding: 2px; border-radius: 3px | | success | background-color: #13a10e; color: #fff; padding: 2px; border-radius: 3px | | focus | background-color: #881798; color: #fff; padding: 2px; border-radius: 3px | | alert | background-color: #ffa500; color: #fff; padding: 2px; border-radius: 3px | | danger | background-color: #dc143c; color: #fff; padding: 2px; border-radius: 3px |

默认别名

d → debug, l → log, i → info, w → warn, e → error

如何使用

创建实例

// debug.ts
import { DebugWeb } from 'debug-web';

export const debug = new DebugWeb({
  app: 'my-app',
  level: process.env.NODE_ENV === 'development' ? 'log' : 'error',
  data: { version: APP_VERSION },
  alias: { s: 'success', f: 'focus' },
  local: true,
});

API

`createDebug` 函数

创建一个支持别名和自定义级别的代理。

<T extends typeof DebugWeb>(options?: CreateDebugOptions, DebugClass?: T) => CustomLogLevels & InstanceType<T>;

日志记录方法

| 级别 | 类型 | |--------------|------------------------------------------------------------------------| | debug | (message?: unknown, ...attrs: unknown[]) => void | | log | (...attrs: unknown[]) => void | | info | (...attrs: unknown[]) => void | | warn | (...attrs: unknown[]) => void | | error | (...attrs: unknown[]) => void | | group | (open?: boolean, level?: DebugLogLevel, ...attrs: unknown[]) => void | | groupEnd | (level?: DebugLogLevel) => void | | dir | (value: unknown, options?: unknown) => void | | dirxml | (...attrs: unknown[]) => void | | trace | (...attrs: unknown[]) => void | | table | (data: unknown, properties?: string[]) => void | | count | (label?: string) => void | | countReset | (label?: string) => void | | time | (label?: string) => void | | timeLog | (label?: string, ...attrs: unknown[]) => void | | timeEnd | (label?: string) => void |

数据处理

| 方法 | 类型 | 注释 | |--------|----------------------------------------------------|---------------------------------------------------| | set | (data: DebugWebData, storage?: boolean) => void | 保存调试数据（合并）。如果 storage=true — 保存到 sessionStorage | | get | (storage?: boolean) => DebugWebData \| undefined | 返回数据的副本。如果传入 true，则从 sessionStorage 获取 | | dump | (keys: string[], options?: DumpOptions) => void | 以表格形式输出数据（忽略日志级别） |

type DebugWebData = Record<string, unknown>

type DumpOptions = {
  level?: DebugLogLevel;
  title?: string | ((data: DebugWebData) => string);
  open?: boolean;
}

级别管理

| 方法 | 类型 | 注释 | |------------------|-----------------|----------| | level (getter) | DebugLogLevel | 获取当前日志级别 | | level (setter) | DebugLogLevel | 设置当前日志级别 |

样式设置

| 方法 | 类型 | 注释 | |------------------|-----------------------------------|--------------| | style (getter) | () => DebugWebStyle | 获取当前样式映射表 | | style (setter) | (styles: DebugWebStyle) => void | 更新样式映射表（将合并） |

type DebugWebStyle = Record<DebugLogLevel, string | undefined>

调试数据

保存任意数据并在控制台中查看：

debug.set({ error: null, user: { id: 1, name: 'John' } });

可以通过 window[prop]（默认是 debug）访问数据。在浏览器控制台中输入：

debug // { error: null, user: {...}, setLevel: f }
debug.setLevel() // 修改日志级别