npm package: @seed-fe/logger
Description: A powerful and flexible logger library
Author: xianghongai
Latest version: 1.1.0

# @seed-fe/logger

## 安装

```bash
# npm
npm install @seed-fe/logger

# yarn
yarn add @seed-fe/logger

# pnpm (推荐)
pnpm add @seed-fe/logger
```

## 简介

提供分级日志输出能力，可以在项目中自行决定在什么环境输出什么级别的日志。

日志级别从低到高如下：

* `trace`
* `debug/log`
* `info`
* `warn`
* `error`

## `trace()/debug()/log()/info()/warn()/error()`

* 接口：`(...args: unknown[]) => void`
* 参数：`args`: 需要输出的内容
* 返回：无
* 用法：同 `console.trace/debug/log/info/warn/error`，例如 `logger.log('hello')` 将输出 `hello`

## `getLevel()`

获取当前日志输出等级；

* 接口：`() => LogLevelName`
* 参数：无
* 返回：当前日志级别 `'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'SILENT'` 中的一个
* 用法：`const currentLevel = logger.getLevel()`

## `setLevel()`

设置当前日志输出等级，一般用于生产环境临时开启日志输出；

* 接口：`(level: LogLevelName, persistent?: boolean) => void`
* 参数：
  * `level`: 日志级别 `'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'SILENT'` 中的一个，`SILENT` 不输出任何日志
  * `persistent`: 是否持久化，默认为 `true`。如果为 `true`，则日志级别会持久化到本地存储中，下次打开页面时会自动恢复，传 `false` 则只在本次会话生效
* 返回：无
* **重要**：所有 logger（包括默认 logger 和具名 logger）共享全局日志级别，任何 logger 调用 setLevel 都会影响全局
* 用法：

  ```typescript
  import logger, { LogLevelName } from '@seed-fe/logger';

  // 默认持久化
  logger.setLevel('DEBUG');

  // 显式持久化
  logger.setLevel('DEBUG', true);

  // 不持久化（仅本次会话）
  logger.setLevel('DEBUG', false);
  ```

## `getLogger`

获取一个新的具名 Logger，所有具名 Logger 的输出前面都会带上该 Logger 的名称，一般用于区分不同模块的日志输出；

* 接口：`(name: string) => Logger`
* 参数：`name`: 具名 Logger 的名称
* 返回：新的 Logger 对象
* 用法：`const featureLogger = logger.getLogger('feature')`，例如 `featureLogger.log('hello')` 将输出 `[feature] hello`

**重要**：所有 logger（包括默认 logger 和具名 logger）共享全局日志级别。具名 logger 只是在输出时添加前缀以区分模块，日志级别控制是全局统一的。

## `configureLogger()`

在应用启动时配置日志行为，例如默认级别、localStorage key、是否启用持久化读写等。

* 接口：`(config: { defaultLevel?: LogLevelName; storageKey?: string | null; enablePersistence?: boolean }) => void`
* 用法：

  ```ts
  import { configureLogger } from '@seed-fe/logger';

  // 应用启动时初始化
  configureLogger({
    defaultLevel: 'ERROR',
    storageKey: '@seed-fe/logger:level', // 默认值，可省略
    enablePersistence: true, // 默认值，可省略
  });

  // 彻底关闭 localStorage 读写（包括“魔法值”）
  configureLogger({
    storageKey: null,
    enablePersistence: false,
  });
  ```

## 不同环境下的日志级别

```typescript
import logger from '@seed-fe/logger';

if (isDevelopment) {
  logger.setLevel('TRACE');
} else {
  logger.setLevel('ERROR');
}
```

实际使用建议：

| 环境   | 推荐级别                      | 理由           |
|:------|:---------------------------|:--------------|
| 本地开发 | `DEBUG` 或 `TRACE`             | 查看详细调试信息     |
| 测试环境 | `INFO`                      | 记录关键流程，减少噪音  |
| 生产环境 | `ERROR`                     | 只记录错误，避免性能影响 |
| 临时调试 | `TRACE` + `persistent: false` | 排查线上问题后恢复    |

## 在 Chrome DevTools Console 中调试

本库在浏览器环境中会自动暴露 `__SEED_FE_LOGGER__` 全局变量，你可以在 Chrome DevTools Console 中直接使用：

```js
// 打开 Chrome DevTools Console (F12)

// 查看当前日志级别
__SEED_FE_LOGGER__.getLevel()

// 临时开启所有日志（不持久化，刷新后恢复）
__SEED_FE_LOGGER__.setLevel('TRACE', false)

// 开启所有日志并持久化（刷新后仍生效）
__SEED_FE_LOGGER__.setLevel('TRACE', true)

// 只看错误日志
__SEED_FE_LOGGER__.setLevel('ERROR')

// 关闭所有日志
__SEED_FE_LOGGER__.setLevel('SILENT')
```

## 高级配置

### 配置全局行为

在应用启动时，可以通过 `configureLogger` 配置全局行为：

```typescript
import { configureLogger } from '@seed-fe/logger';

configureLogger({
  // 默认日志级别
  defaultLevel: 'ERROR',

  // 持久化的 localStorage key
  storageKey: '@my-app/logger:level',

  // 是否允许持久化
  enablePersistence: false,
});
```

更多设计细节和架构说明，请参阅 [DESIGN_NOTES.md](./DESIGN_NOTES.md)。

## Tree-shaking 说明

本库在浏览器环境中会自动暴露全局变量 `window.__SEED_FE_LOGGER__`，这是一个有意为之的顶层副作用，用于方便生产环境调试。

某些打包器在极度激进的 tree-shaking 配置下可能会保留该模块。如果你的应用对包体积极度敏感，可以配置打包器的 `sideEffects` 字段来优化。