From 85aa9b2a219cf5460baacf919a37c7a448760306 Mon Sep 17 00:00:00 2001 From: neverland Date: Mon, 23 Mar 2026 14:41:39 +0800 Subject: [PATCH 1/4] docs: add customLogger config docs --- website/docs/en/api/javascript-api/core.mdx | 2 + website/docs/en/config/_meta.json | 1 + website/docs/en/config/custom-logger.mdx | 41 +++++++++++++++++++++ website/docs/en/guide/migration/vite.mdx | 2 +- website/docs/zh/api/javascript-api/core.mdx | 2 + website/docs/zh/config/_meta.json | 1 + website/docs/zh/config/custom-logger.mdx | 41 +++++++++++++++++++++ website/docs/zh/guide/migration/vite.mdx | 2 +- website/theme/rsbuildPluginOverview.ts | 4 ++ 9 files changed, 94 insertions(+), 2 deletions(-) create mode 100644 website/docs/en/config/custom-logger.mdx create mode 100644 website/docs/zh/config/custom-logger.mdx diff --git a/website/docs/en/api/javascript-api/core.mdx b/website/docs/en/api/javascript-api/core.mdx index 22ec3a1420..7a91d1f001 100644 --- a/website/docs/en/api/javascript-api/core.mdx +++ b/website/docs/en/api/javascript-api/core.mdx @@ -423,6 +423,8 @@ In Rsbuild, most options that support function values use this rule, such as `to Creates an isolated logger instance based on [rslog](https://github.com/rstackjs/rslog). Use this when you need custom log levels or overrides without mutating the shared [logger](#logger) singleton. +The created logger can also be passed to the [customLogger](/config/custom-logger) config option. + - **Example:** ```ts diff --git a/website/docs/en/config/_meta.json b/website/docs/en/config/_meta.json index ea27675783..ab50b73bee 100644 --- a/website/docs/en/config/_meta.json +++ b/website/docs/en/config/_meta.json @@ -18,6 +18,7 @@ "log-level", "split-chunks", "environments", + "custom-logger", { "type": "dir-section-header", "name": "dev", diff --git a/website/docs/en/config/custom-logger.mdx b/website/docs/en/config/custom-logger.mdx new file mode 100644 index 0000000000..b1f12f463e --- /dev/null +++ b/website/docs/en/config/custom-logger.mdx @@ -0,0 +1,41 @@ +--- +description: 'Use customLogger to attach a logger instance to the current Rsbuild instance. Create it with createLogger() for isolated logging.' +--- + +# customLogger + +- **Type:** `Logger` +- **Default:** `undefined` + +Uses a custom logger instance for the current Rsbuild instance. + +## Example + +Use [createLogger](/api/javascript-api/core#createlogger) to create a new logger instance. + +```ts title="rsbuild.config.ts" +import { createLogger, defineConfig } from '@rsbuild/core'; + +const logger = createLogger({ + level: 'warn', +}); + +export default defineConfig({ + customLogger: logger, +}); +``` + +## Global logger vs instance logger + +Rsbuild provides two ways to access a logger: + +- The global logger is the shared [logger](/api/javascript-api/core#logger) singleton exported from `@rsbuild/core`. +- The instance logger is the logger associated with the current Rsbuild instance, exposed as [rsbuild.logger](/api/javascript-api/instance#rsbuildlogger) or [api.logger](/plugins/dev/core#apilogger) in plugins. + +When `customLogger` is not set, the instance logger falls back to the shared global logger. When `customLogger` is set, the instance logger references that custom logger instead. + +## Version history + +| Version | Changes | +| ------- | ------------------------------- | +| v2.0.0 | Added the `customLogger` option | diff --git a/website/docs/en/guide/migration/vite.mdx b/website/docs/en/guide/migration/vite.mdx index e5529ebbb7..e5ca83a2a8 100644 --- a/website/docs/en/guide/migration/vite.mdx +++ b/website/docs/en/guide/migration/vite.mdx @@ -123,7 +123,7 @@ Here is the corresponding Rsbuild configuration for each Vite option: | logLevel | [logLevel](/config/log-level) | | cacheDir | [buildCache](/config/performance/build-cache) | | publicDir | [server.publicDir](/config/server/public-dir) | -| customLogger | [Custom logger](/api/javascript-api/core#custom-logger) | +| customLogger | [customLogger](/config/custom-logger) | | assetsInclude | [source.assetsInclude](/config/source/assets-include) | | resolve.alias | [resolve.alias](/config/resolve/alias) | | resolve.dedupe | [resolve.dedupe](/config/resolve/dedupe) | diff --git a/website/docs/zh/api/javascript-api/core.mdx b/website/docs/zh/api/javascript-api/core.mdx index ab7ed95af4..15efdda6ac 100644 --- a/website/docs/zh/api/javascript-api/core.mdx +++ b/website/docs/zh/api/javascript-api/core.mdx @@ -423,6 +423,8 @@ const mergedConfig = { 基于 [rslog](https://github.com/rstackjs/rslog) 创建一个独立的 logger 实例。当你需要自定义日志级别或覆盖日志方法，同时又不想修改共享的 [logger](#logger) 单例时，可以使用该方法。 +创建出的 logger 也可以传给 [customLogger](/config/custom-logger) 配置项使用。 + - **示例：** ```ts diff --git a/website/docs/zh/config/_meta.json b/website/docs/zh/config/_meta.json index 0bddad15b1..39c488e76f 100644 --- a/website/docs/zh/config/_meta.json +++ b/website/docs/zh/config/_meta.json @@ -18,6 +18,7 @@ "log-level", "split-chunks", "environments", + "custom-logger", { "type": "dir-section-header", "name": "dev", diff --git a/website/docs/zh/config/custom-logger.mdx b/website/docs/zh/config/custom-logger.mdx new file mode 100644 index 0000000000..ead6b0a792 --- /dev/null +++ b/website/docs/zh/config/custom-logger.mdx @@ -0,0 +1,41 @@ +--- +description: '为当前 Rsbuild 实例指定独立的 logger。推荐配合 createLogger() 创建，避免修改共享 logger。' +--- + +# customLogger + +- **类型：** `Logger` +- **默认值：** `undefined` + +为当前 Rsbuild 实例指定一个自定义 logger。 + +## 示例 + +使用 [createLogger](/api/javascript-api/core#createlogger) 来创建一个新的 logger 实例。 + +```ts title="rsbuild.config.ts" +import { createLogger, defineConfig } from '@rsbuild/core'; + +const logger = createLogger({ + level: 'warn', +}); + +export default defineConfig({ + customLogger: logger, +}); +``` + +## 全局 logger 与实例 logger + +Rsbuild 提供了两种获取 logger 的方式： + +- 全局 logger 是从 `@rsbuild/core` 导出的共享 [logger](/api/javascript-api/core#logger) 单例。 +- 实例 logger 是当前 Rsbuild 实例关联的 logger，可以通过 [rsbuild.logger](/api/javascript-api/instance#rsbuildlogger) 获取，在插件中也可以通过 [api.logger](/plugins/dev/core#apilogger) 获取。 + +当未配置 `customLogger` 时，实例 logger 会回退到共享的全局 logger；当配置了 `customLogger` 时，实例 logger 则会引用该自定义 logger。 + +## 版本历史 + +| 版本 | 变更内容 | +| ------ | ------------------------ | +| v2.0.0 | 新增 `customLogger` 选项 | diff --git a/website/docs/zh/guide/migration/vite.mdx b/website/docs/zh/guide/migration/vite.mdx index fa8553e92b..f64a3dae54 100644 --- a/website/docs/zh/guide/migration/vite.mdx +++ b/website/docs/zh/guide/migration/vite.mdx @@ -123,7 +123,7 @@ Rsbuild 会在构建时自动注入 `