企业官网建设流程全解析

• 后端
• Web框架

think-logger3 是 ThinkJS 3.x 官方配套的日志模块，底层基于 log4js 6.x 构建，以 Adapter 方式提供控制台、文件、按日期轮转文件以及完全自定义四种日志能力。本文基于当前仓库中 packages/think-logger3/README.md 展开，并结合该包的源码与测试用例，帮助你在独立 Node.js 项目或 ThinkJS 3.x 应用中快速接入日志系统，掌握日志轮转、按日期归档、log4js 配置透传等实战技能。

一、模块定位与核心设计

think-logger3 的包名为think-logger3（仓库目录为 packages/think-logger3），package.json中描述为 "logger for ThinkJS 3.x"。它并非从零实现的日志库，而是对 log4js）。

其核心设计理念是Adapter（适配器）模式：通过handle配置项指定底层日志输出方式，屏蔽 log4js 复杂的appenders/categories配置结构，让使用者以极简配置获得开箱即用的日志能力。从源码看，Logger类将trace、debug、info、warn、error、getLogger六个方法绑定到底层 adapter 实例上，并对外暴露四个静态 Adapter 类：

• Logger.Basic：直接透传 log4js 原生配置；
• Logger.Console：输出到控制台（默认）；
• Logger.File：输出到文件，支持按文件大小轮转；
• Logger.DateFile：输出到文件，支持按日期模式轮转。

实现见 src/index.js。

二、安装

在任意 Node.js 项目中执行：

npm install think-logger3

如果你正在使用 ThinkJS 3.x 应用，则该包已作为框架核心依赖被引入——packages/thinkjs/package.json 中声明了"think-logger3": "^1.4.0"，框架启动时即会自动实例化全局 logger（详见下文“与 ThinkJS 3.x 框架集成”一节），无需手动安装。

三、基本用法：控制台日志

1. 最简单的日志输出

const Logger = require('think-logger3'); const logger = new Logger(); logger.debug('Hello World');

不传任何配置时，Logger构造函数中的handle默认为ConsoleAdapter（见 src/index.js），日志直接输出到控制台。

2. 四个常用日志方法

logger.info('info log'); logger.debug('debug log'); logger.warn('warn log'); logger.error('error log');

除上述四种方法外，模块还额外提供了trace与getLogger方法。构造函数在实例化时会逐一校验 adapter 是否实现了这些方法，若缺失会直接抛出形如adapter function xxx not exist!的断言错误（见 src/index.js），这从机制上保证了所有 Adapter 具备一致的日志 API。

3. 控制台输出的默认格式

从 Console adapter 源码 可以看到，控制台日志有两个默认行为：

• 默认级别：未指定level时取'ALL'（不拦截任何级别，全部输出），配置了level则自动转为大写；
• 默认布局：{ type: 'pattern', pattern: '%[[%d] [%z] [%p]%] - %m' }，其中%d为时间、%z为时区、%p为日志级别、%m为日志消息，输出形如[2026-10-14T12:34:24.000] [Asia/Shanghai] [INFO] - Hello World。

四、Adapter 工作机制：配置如何转译为 log4js

所有 Adapter 都继承自 src/adapter/base.js 中的基础类。基类持有 log4js 的 logger 实例，暴露configure(config)、setLogger(config, category)、getLogger()三个方法，分别对应 log4js 的配置加载、logger 获取等底层能力。

关键的扩展点是formatConfig(config)方法：每个 Adapter 通过覆写它，把用户传入的扁平配置（如filename、maxLogSize）组装成 log4js 需要的appenders+categories结构，再交给log4js.configure()执行。例如 Console adapter 组装出：

{ appenders: { console: { type: 'console', layout } }, categories: { default: { appenders: ['console'], level } } }

File adapter 则组装出{ type: 'file', filename, maxLogSize, backups, absolute, layout, mode }（见 src/adapter/file.js）。理解这一机制后，你就知道：所有传给new Logger()的配置，最终都会被映射为 log4js 的 appender 配置，log4js 支持的能力（如布局、级别过滤）在这里都能使用。

五、文件日志：File Adapter（按大小轮转）

1. 高级用法示例

const Logger = require('think-logger3'); const logger = new Logger({ handle: Logger.File, filename: __dirname + '/debug.log', maxLogSize: 50 * 1024, // 50KB backups: 10 // 最多保留的分片数量 }); logger.debug('Hello World');

注意：README 示例中注释写的是//50M，但50 * 1024 = 51200字节，实际约 50KB。maxLogSize的单位是字节，请按真实需求换算，避免日志过早或过晚轮转。

2. 轮转行为

启用后，初始日志写入debug.log；当文件达到maxLogSize后，新建debug.log.1继续写入；文件继续增长则依次产生debug.log.2、debug.log.3……当分片数量达到backups上限时，最旧的日志分片会被自动删除，实现"固定数量分片、总量可控"的循环日志。

3. 配置项说明

其中level与mode两项是 file.js 源码 中明确支持、但 README 未展开的补充项。

六、按日期轮转：DateFile Adapter

1. 用法示例

const Logger = require('think-logger3'); const logger = new Logger({ handle: Logger.DateFile, filename: __dirname + '/debug.log', pattern: '-yyyy-MM-dd', alwaysIncludePattern: false });

2. 轮转行为

初始日志写入debug.log。当当前日志条目的日期模式与上一个条目不同时（典型场景是跨天），旧文件会被重命名为带日期的文件，例如debug.log→debug.log-2026-10-14，同时新建一个空的debug.log继续写入。这样每天的日志都被归档到独立文件，便于按天检索与清理。

3. pattern 支持的占位符

以下字符串会在文件名模式中被识别并替换为实际日期/时间：

4. alwaysIncludePattern 的两种行为

• alwaysIncludePattern: false（默认）：初始文件名为debug.log，到达新日期时把旧文件重命名为debug.log-2017-03-12这类带日期后缀的文件；
• alwaysIncludePattern: true：初始文件名直接就是debug.log-2017-03-12（从一开始就带日期后缀），午夜时不会发生重命名，而是直接新建debug.log-2017-03-13写入新日志。

5. 配置项说明

mode与numBackups两项来自 datefile.js 源码，是 README 之外的补充配置。

七、完全自定义：Basic Adapter 直接使用 log4js 配置

当上述 Adapter 的配置无法满足需求时，使用Logger.Basic，所有属性与 log4js 原生配置完全一致（唯一的例外是handle属性，它用来指定 Adapter 类型）：

const Logger = require('think-logger3'); const logger = new Logger({ handle: Logger.Basic, appenders: { everything: { type: 'file', filename: 'all-the-logs.log' }, emergencies: { type: 'file', filename: 'oh-no-not-again.log' }, 'just-errors': { type: 'logLevelFilter', appender: 'emergencies', level: 'error' } }, categories: { default: { appenders: ['just-errors', 'everything'], level: 'debug' } } });

上述配置实现了"普通日志写入all-the-logs.log，error 级别日志额外写入oh-no-not-again.log"的多文件分流。由于 Basic Adapter 的formatConfig在 base.js 中默认原样返回配置，因此 log4js 的完整配置对象（appenders、categories、levels、pm2 等）都可以直接使用，具体配置项参考 log4js 官方 API 文档的 Configuration Object 章节。

八、与 ThinkJS 3.x 框架集成

think-logger3 在 ThinkJS 3.x 框架中承担全局日志职责，框架启动阶段完成实例化：

1. 全局 logger 的初始化

在 packages/thinkjs/lib/loader.js 中可以看到：

think.logger = new Logger(helper.parseAdapterConfig(think.config('logger')), true);

即框架读取应用配置中的logger字段，经think-helper的parseAdapterConfig解析后实例化全局think.logger。此后应用任何位置都可以通过think.logger.info(...)、think.logger.error(...)记录日志——框架自身的启动信息、转译信息、未捕获异常处理等均复用了该实例（见 packages/thinkjs/lib/application.js、packages/thinkjs/lib/config/config.js）。

2. 应用中的配置方式

ThinkJS 3.x 应用的日志配置遵循框架的Adapter 配置规范，通常写在src/config/adapter.js的logger字段中。parseAdapterConfig的解析规则（见 packages/think-helper/index.js）支持如下两种写法：

• 直接指定handle与参数：

// src/config/adapter.js module.exports = { logger: { handle: 'file', // 对应 Logger.File，也可用 'console' | 'datefile' filename: '/data/logs/debug.log', maxLogSize: 5 * 1024 * 1024, // 5MB backups: 10, absolute: true // filename 为绝对路径时置为 true } };

• 多类型并存、按type切换（推荐用于多环境切换）：

module.exports = { logger: { type: 'datefile', common: { absolute: true }, console: { handle: 'console' }, datefile: { handle: 'datefile', filename: '/data/logs/debug.log', pattern: '-yyyy-MM-dd', alwaysIncludePattern: true } } };

框架会读取type字段对应的子配置并合并common公共项，最终传给new Logger(...)实例化。相关解析规则可对照 think-loader 的 adapter 加载逻辑 与 parseAdapterConfig 测试用例。

3. 控制器与上下文中便捷访问

src/extend.js 为 ThinkJS 扩展了快捷访问入口：

• 在**上下文（ctx）**中：ctx.logger会基于this.config('logger')惰性创建并缓存 logger 实例；
• 在**控制器（controller）**中：this.logger直接代理this.ctx.logger。

因此控制器里可以直接写this.logger.info('...')，与think.logger等效但更符合分层语义。

九、GELF 适配器（源码补充）

除 README 重点介绍的四种 Adapter 外，源码中还包含一个GELF（Graylog Extended Log Format）适配器（见 src/adapter/gelf.js），用于把日志以 GELF 协议发送到 Graylog 等集中式日志服务器，支持配置项：

该适配器在 README 中未展开说明，需要集中日志收集时可参考上述源码进行配置。

十、测试用例与验证方式

仓库为 think-logger3 提供了两组基于 Node 内置node:test的测试，可直接验证模块行为：

1. 控制台输出测试

test/console.js 拦截process.stdout.write，依次调用trace、debug、info、warn、error五个方法，断言每个级别的输出都包含'Hello World'，验证默认 Console 适配器的基本输出能力。

2. 文件写入测试

test/file.js 使用 File 适配器写入临时文件，分别调用五个日志方法后等待 500ms，再读取文件内容，断言其中'Hello World'出现的次数与调用次数一致，验证文件日志落盘正确性。

在包目录下运行测试：

# 在 packages/think-logger3 目录下 pnpm test # eslint + 覆盖率测试 pnpm run test-cov # 仅运行测试

十一、TypeScript 支持

think-logger3 随包提供了类型声明文件 index.d.ts，声明了Logger接口（debug/info/warn/error）、LoggerConstructor（静态属性Basic/Console/File/DateFile）以及Base接口（configure/setLogger/formatConfig），TypeScript 项目引入后可直接获得类型提示。

十二、小结与选型建议

think-logger3 以极薄的封装层复用了 log4js 的成熟能力：日常使用只需handle+ 少量参数即可完成配置；需要深度定制时又能通过Basic适配器无缝透传 log4js 全部配置。配合 ThinkJS 3.x 的 adapter 配置规范，可以轻松实现按环境（开发/生产）切换控制台、文件、按日期归档等日志策略。该模块以 MIT 协议开源（见 package.json 的license字段），可放心在商业项目中集成使用。

• 后端
• Web框架