核心概念
三个想法几乎能解释 Logaria 的全部行为：两种过滤模式、谁拥有作用域，以及为什么运行时——而不是打包工具——才是唯一真理来源。本页就是各个操作指南默认你已经掌握的模型。
级别模式与规则模式
Logaria 在两种模式之一下过滤，而判断你处于哪种模式的规则很简单：
如果解析后的配置有零条规则，你处于 级别模式；如果有一条或更多，你处于规则模式。
// 级别模式——`levels` 就是允许列表。
setLoggerConfig({ levels: ['warn', 'error'] });
// 规则模式——一条规则就把配置变成聚焦的允许列表。
setLoggerConfig({
levels: ['warn', 'error'],
rules: {
'build-flow': { group: 'build.pipeline', levels: ['info', 'warn'] },
},
});两种模式在每个关键点上都不同：
| 级别模式（无规则） | 规则模式（≥ 1 条规则） | |
|---|---|---|
| 过滤依据 | 全局 levels 允许列表 | 规则匹配（main / group / message）且该规则的有效级别 |
| 未命中的日志 | 不适用 | 丢弃——没有回退到 levels |
levels 的角色 | 允许列表本身 | 规则中 levels: 'inherit' 的默认值 |
logger.debug() | 仅当 debug: true 时显示 | 始终被屏蔽 |
debug: true 额外做 | 显示 debug() + 附加耗时 | 仅给非 debug 日志加 [label] 前缀 + 耗时 |
INFO
空的 rules 对象，或全部设为 'off' 的规则，会被规范化为没有规则——因此配置仍处于级别模式。
一条日志如何被决定
当你调用一个日志器方法时，Logaria 按固定顺序决定可见性：
- 解析配置。
plugins注册规则模板 →extends启用具名预设配置 →rules作为最后一层覆盖。 - 检查是否有规则。 解析后没有规则就走级别模式，否则走规则模式。
- 级别模式——日志的级别在
levels里就显示，否则屏蔽。 - 规则模式——保留作用域命中该日志的规则（
main精确；group/message精确或 glob）。其中，有贡献的规则是那些有效级别包含此日志级别的规则。只要存在至少一条有贡献的规则，日志就显示。 - 有效级别：规则若设了
rule.levels就用它，否则用配置的levels，再否则用内置默认（['info', 'success', 'warn', 'error']）。
debug 模式下显示的标签只来自有贡献的规则——一条命中作用域但级别不符的规则，既不显示日志也不贡献标签。
匹配
main 精确匹配——即便取值含 * 也按字面处理。group 与 message 也默认精确匹配，除非它们含有 glob 字符（*、?、[]、{}），此时升级为 glob 匹配。
两种模式下的 Debug
debug 是唯一一个含义随模式而变的开关：
- 级别模式——
debug: true显示logger.debug()输出，并给传入耗时选项的可见非 debug 日志附加耗时。 - 规则模式——
logger.debug()始终被屏蔽，即便debug: true也一样。该标志只给规则放行的非 debug 日志加上命中的[label]前缀与耗时；永远不会显示debug()。
因此只要解析出任意规则，logger.debug() 就会沉默。如果你需要在规则下输出诊断信息，把它提升到 info，或加一条专门针对它的规则。见 运行时配置 — Debug 模式 了解级别模式开关，以及 规则与预设 了解规则模式。
归属与作用域
每个日志器都从一个作用域读取配置。只有一个默认作用域，外加任意数量的显式作用域，而默认作用域的归属是排他的。
| 状态 | 所有者 | 入口 | 行为 |
|---|---|---|---|
| 默认作用域，应用拥有 | 应用 | logaria | setLoggerConfig / resetLoggerConfig 设置配置 |
| 默认作用域，插件受控 | 构建插件 | logaria + logaria/plugin | 配置以构建期常量注入；运行时改写函数抛错 |
| 显式作用域 | 宿主集成 | logaria/core | 创建作用域日志器前先用 setScopedLoggerConfig 注册 |
插件控制下，调用运行时改写函数会抛出（原文）：
logaria is controlled by loggerPlugin.vite({ config }). setLoggerConfig(...) and resetLoggerConfig() cannot be used in this runtime; update the loggerPlugin.vite({ config }) option in your bundler config instead.显式作用域永不触碰默认作用域。createScopedLogger() 要求其作用域先被注册，缺失时抛错——Logaria 拒绝悄悄回退到默认作用域。
同一时间只有一个所有者
默认作用域同一时间只有一个所有者。传递依赖绝不应调用 setLoggerConfig——它应当注册显式作用域，这样就无法悄悄改向或静音应用的日志。
原因见 为什么是 Logaria — 为什么强调显式归属；用法见 作用域集成。
运行时始终是唯一真理
运行时过滤是“什么会输出”的唯一真理来源。构建插件是叠加在其上的优化：它在构建期执行与运行时相同的屏蔽判断，只删除它能证明已经是死代码的调用。
由此得到两条性质：
- 关掉插件，哪些日志会输出不会改变。 裁剪移除的本就是永远过不了过滤的调用。
- 两者不会漂移。 插件控制下运行时改写函数会抛错，因此“插件裁掉的”与“运行时允许的”出自同一份配置。
裁剪是保守的
只有当每条静态事实都成立时才移除调用：命名且无别名的 createLogger 导入、字面量 main / group / message、从未被重新赋值的绑定、独立语句，以及开启了 treeshake: true 的构建上下文。任何动态写法都会留在打包产物中并回退到运行时过滤。见 构建插件 — 裁剪覆盖范围。