rlog-js

一个现代化的 Node.js 日志库，完全使用 TypeScript 编写，提供完整的类型支持。

特性

• 完整的 TypeScript 支持
• 可设置时区
• 自定义时间格式
• 类型着色
• 字符串着色
• 敏感词加密
• 可显示进度条
• 分别设定某个日志输出到屏幕或文件
• 平替console.log，无缝迁移，自动识别日志等级
• 多行输出优化
• 自定义连接符
• rlog.exit()安全退出方法与退出钩子

安装

使用npm进行安装：

npm install rlog-js

使用示例

JavaScript

使用rlog-js非常简单，首先导入rlog-js:

const Rlog = require("rlog-js");

然后创建一个Rlog实例:

const rlog = new Rlog();

TypeScript

rlog-js 完全使用 TypeScript 编写，提供原生的类型支持：

import Rlog from "rlog-js";

const rlog = new Rlog({
  enableColorfulOutput: true,
  logFilePath: "logs.txt",
  timezone: "Asia/Shanghai",
});

rlog.info("This is an information log");
rlog.warn("This is a warning log");

基础用法

接下来就可以使用各种接口来输出日志了。 如果你的项目之前一直是用console.log来输出日志，那么直接替换所有console为rlog即可一步到位。

具体来说，./test.js中有大量对rlog的调用示例，以供查看。

一个最简单的使用示例如下：

const Rlog = require("rlog-js");

const rlog = new Rlog({
  enableColorfulOutput: true,
  logFilePath: "logs.txt",
});

rlog.config.setConfig({
  timeFormat: "YYYY-MM-DD HH:mm:ss",
  timezone: "Asia/Shanghai",
  blockedWordsList: ["password", "secret"],
});

rlog.info("This is an information log");
rlog.log("This is an automatically recognized type of log output");
rlog.warn("This is a warning log");
rlog.error("This is an error log");
rlog.success("This is a success log");
rlog.exit("This is a secure exit method");

进阶

rlog致力于成为nodejs端最好用的日志系统。以下是一些进阶使用方式：

配置

有三种方法可修改RLog的配置：

// Apply configuration when creating an instance
// 创建实例时应用配置
const rlog = new Rlog({
  logFilePath: "./log.txt",
  timezone: "Asia/Shanghai",
  autoInit: false,
});

// Use setConfig to set configuration
// 使用 setConfig 设置配置
rlog.config.setConfigGlobal({
  blockedWordsList: ["world", "[0-9]{9}"],
});
rlog.config.setConfig({
  silent: true
})

// Set config directly
// 直接设置配置
rlog.config.logFilePath = './log.txt'
rlog.config.timezone = 'Asia/Shanghai'

其中，setConfig 用于实例级配置，setConfigGlobal 用于全局默认配置。

自动判断日志级别

rlog提供了一个特殊的rlog.log()，以平替console.log。此方法通过关键词匹配，自动确定日志是否属于 error、warning 或 success，否则为 info。

仅在屏幕/文件中输出

有些时候，日志输出并不一定要做到屏幕显示与文件同步。
例如，要显示某个操作的进度(eg:11/100 11%)，就适合只显示在屏幕上而不应被写入文件中。
而大段的错误信息，例如某网页/api请求后返回了错误的状态码，你可以仅在屏幕上显示一个大致的错误信息，而在日志文件中输出整个返回的响应，方便定位错误的同时保证输出的整洁性。

rlog.info("This will be shown both screen and file");
rlog.file.info("file only")
rlog.screen.info("screen only")

注：file与screen方式不提供自动判断类型的.log()方法，毕竟如果使用这个特性你肯定知道自己log的类型是什么。

强制退出

日志系统免不了与错误打交道，rlog提供了一个 rlog.exit(message)，你可以轻松的通过调用此函数来安全终止程序的运行。调用后，会在屏幕与文件中记录错误信息，然后阻塞进程，直到日志保存完后退出。
不推荐使用process.exit的方法来关闭进程。由于文件日志写入是异步的，直接这样退出会导致日志无法成功保存，请使用rlog.exit来退出。

退出钩子

很多程序在错误的时候会返回点什么统一的提示，例如给个Github Issue地址或者文档地址；或者完成什么配置保存工作或者关闭文件之类的事。显然每个错误的地方都写一条太麻烦了，你可以通过注册一个统一的 onExit，在调用 rlog.exit()之前做你想要的事。

rlog.onExit(() => {
  rlog.warn("rlog.exit() called and event triggered.");
});

字符串着色

配置customColorRules来实现字符串的着色。支持正则表达式。

rlog.setConfig({
    customColorRules: [
       {
          reg: "[a-zA-z]+://[^\\s]*",
          color: "cyan",
        },
    ],
});

支持的颜色：

敏感词加密

配置blockedWordsList来实现敏感词的加密，或者说，日志脱敏。支持正则表达式。

rlog.setConfig({
    blockedWordsList: [
       "password",
       "[0-9]{9}"
    ],
});

你也可以在碰见敏感词的时候，就将其push到rlog.config.blockedWordsList中。

进度条

在屏幕上显示一个进度条真是太酷了。你可以简单的调用 rlog.progress(num, max);，rlog会自动计算比例，并显示一个进度条。
多次调用porgress时，屏幕上只会保留最后一个进度条。

const Rlog = require("rlog-js");
const rlog = new Rlog();

rlog.log('当一个progress单独出现时，不会影响上下文')
rlog.progress(168,1668)
rlog.log('当更多progress一块出现时，屏幕只显示最新的')

let i = 0
let a = setInterval(()=>{
    i +=1
    if (i == 234) {
        clearImmediate(a)
        process.exit()
    }
    rlog.progress(i,233)
},10)

进度条只会在screen中输出，随便调用，不会污染日志。

指定joinChar

有的时候你可能想让程序整齐一点，输出多行内容的时候，代码也能赏心悦目，与输出的格式相同：

// bad
rlog.info(`line1
line2`);

// bad
rlog.info("line1\nline2")

// good
rlog.config.joinChar = "\n"
rlog.info(
  "line1",
  "line2"
)

自动初始化

通常情况下，rlog会在创建实例时自动初始化日志文件。
可在一些特殊情况下，例如Next.js 的构建流程会在多个阶段甚至子进程/线程中多次加载并实例化日志库，会导致日志文件被多次创建。
在这种情况下，你可以通过设置autoInit为false来禁用自动初始化。
在没有自动初始化的情况下，rlog也会在被首次调用时自行初始化。
如果你想手动控制初始化的时机，可以在创建实例后调用rlog.file.init()来初始化日志文件。

静默模式

rlog会自动输出一些信息，例如初始化日志文件的路径。
你可以通过设置silent为true来启用静默模式，让rlog只输出你手动调用的日志。

接口

Rlog

rlog.methodName();

Rlog是rlog-js的主类，用于创建日志实例，会自动调用File和Screen方法。

| 方法 | 描述 | | ------------------- | ------------------------------------------------------ | | info(message) | 打印一条信息日志，并将其写入日志文件 | | warn(message) | 打印一条警告日志，并将其写入日志文件 | | error(message) | 打印一条错误日志，并将其写入日志文件 | | success(message) | 打印一条成功日志，并将其写入日志文件 | | exit(message) | 打印一条退出日志，并将其写入日志文件，然后终止应用程序 | | log(message) | 自动识别message类型并调用相关函数 | | progress(num,max) | 打印进度条，num为当前进度，max为总进度 |

Config

rlog.config;

Config是一个用于配置rlog-js的类。可设置的项，详见#配置项。

| 配置项 | 类型 | 默认值 | 描述 | | ---------------------- | ------------------------------------- | ------------------------- | ---------------------------------------- | | enableColorfulOutput | boolean | true | 是否启用彩色输出 | | logFilePath | string | undefined | 日志文件的路径，默认表示不将日志写入文件 | | timeFormat | string | "YYYY-MM-DD HH:mm:ss.SSS" | 时间的格式 | | timezone | string | "GMT" | 时区 | | blockedWordsList | Array<string> | [] | 需要屏蔽的敏感词列表 | | customColorRules | Array<{reg: string, color: string}> | 预设规则 | 自定义的颜色规则列表 | | screenLength | number | 自动获取 | 屏幕输出的最大宽度 | | joinChar | string | " " | 传入多个参数时的连接符 | | silent | boolean | false | 是否启用静默模式 | | autoInit | boolean | true | 是否自动初始化日志文件 |

Config类方法：

| 方法 | 描述 | | ---------------------- | -------------------------------------------------- | | setConfig(obj) | 根据传入的对象更新配置 | | setConfigGlobal(obj) | 根据传入的对象更新配置，并将更新后的配置应用到全局 |

Toolkit

rlog.toolkit.methodName();

Toolkit是一个工具类，用于提供一些常用的工具函数。

| 方法 | 描述 | | ---------------------------- | -------------------------------------------- | | checkLogFile(path) | 检查日志文件是否存在，如果不存在则创建该文件 | | colorizeString(str) | 根据配置的颜色规则对字符串进行着色 | | formatTime() | 根据配置的时间格式和时区生成时间字符串 | | encryptPrivacyContent(str) | 对字符串中的敏感内容进行加密 | | colorizeType(variable) | 根据变量的类型对其进行着色 | | padLines(str, width) | 对字符串中除第一行外的每一行进行缩进 |

Screen

rlog.screen.methodName();

Screen是用于在控制台打印日志的类。调用此方法，将仅在屏幕中输出，不会写入至文件。

| 方法 | 描述 | | ------------------------ | -------------------------------- | | info(message, time) | 打印一条信息日志 | | warn(message, time) | 打印一条警告日志 | | error(message, time) | 打印一条错误日志 | | success(message, time) | 打印一条成功日志 | | exit(message, time) | 打印一条退出日志，并终止应用程序 |

File

rlog.file.methodName();

File是用于将日志写入文件的类。调用此方法，若已设置日志文件路径，将会写入至文件，不会在屏幕输出。

| 方法 | 描述 | | ------------------------ | ------------------------------------------------------ | | init() | 初始化日志文件，如果配置了日志文件路径。不需要手动调用 | | writeLogToStream(text) | 将日志写入文件流 | | writeLog(text) | 将日志写入文件 | | info(message, time) | 写入一条信息日志 | | warn(message, time) | 写入一条警告日志 | | error(message, time) | 写入一条错误日志 | | success(message, time) | 写入一条成功日志 | | exit(message, time) | 写入一条退出日志，并终止应用程序 |

配置项

rlog-js还提供了一些配置选项，可以在创建Rlog实例时进行配置，也可以使用setConfig()和setConfigGlobal()或者以rlog.config[config] = <value>的方式设置。

以下是可用的配置选项及其默认值:

{
    enableColorfulOutput: true, // 是否启用彩色输出
    logFilePath: undefined,     // 日志文件路径，如果不设置则不会输出到文件
    timeFormat: "YYYY-MM-DD HH:mm:ss.SSS", // 时间格式
    timezone: "GMT",      // 时区
    joinChar: " ",        // 指定传入多参数时应如何连接
    blockedWordsList: [], // 需要屏蔽的词汇列表
    autoInit: true,       // 是否自动初始化日志文件
    customColorRules: [   // 自定义颜色规则
        {
            reg: "false",
            color: "red",
        },
        {
            reg: "true",
            color: "green",
        },
        {
            reg: "((2(5[0-5]|[0-4]\\d))|[0-1]?\\d{1,2})(\\.((2(5[0-5]|[0-4]\\d))|[0-1]?\\d{1,2})){3}",
            color: "cyan",
        },
        {
            reg: "[a-zA-z]+://[^\\s]*",
            color: "cyan",
        },
        {
            reg: "\\d{4}-\\d{1,2}-\\d{1,2}",
            color: "green",
        },
        {
            reg: "\\w+([-+.]\\w+)*@\\w+([-.]\\w+)*\\.\\w+([-.]\\w+)*",
            color: "cyan",
        },
        {
            reg: "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}",
            color: "cyan",
        },
        {
            reg: "(w+)s*:s*([^;]+)",
            color: "cyan",
        },
    ]
}

关于如何更改配置项，请查看#配置部分。

开发

从源码构建

本项目使用 TypeScript 编写，需要先编译才能使用：

# 克隆仓库
git clone https://github.com/RavelloH/RLog.git
cd RLog

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 运行测试
npm test

项目结构

RLog/
├── src/           # TypeScript 源码
│   └── index.ts   # 主文件
├── dist/          # 编译输出 (自动生成)
│   ├── index.js   # 编译后的 JS
│   └── index.d.ts # 类型声明文件
├── test.js        # 测试文件
└── tsconfig.json  # TypeScript 配置

类型安全

使用 TypeScript 重写后，所有潜在的类型错误都在编译期被捕获：

• ✅ 所有 chalk 颜色调用都有类型检查
• ✅ 配置项有完整的接口定义
• ✅ 异步操作有正确的 Promise 类型
• ✅ 所有类方法都有明确的返回类型

License

MIT License