介绍

Logaria 是一款面向 TypeScript 包、脚本、CLI 与浏览器代码的轻量、框架无关日志器。它为应用代码提供精简的日志 API，把配置归属权讲得清清楚楚，并可选地搭配构建插件，在构建期裁掉静态可证明被关闭的日志调用。

最小可用的日志器只有几行：

import { createLogger } from 'logaria';

const logger = createLogger({ main: '@acme/docs' }).getLoggerByGroup('build.pipeline');

logger.info('build started');

核心想法：让日志消失

一个日志器应当按这个顺序让你做三件事：

1. 在库、脚本与应用代码里自由地写日志，全靠一组很小的 API。
2. 在 运行时过滤它们——按级别、按组、按消息或按预设规则——切换可见性永远无需重新编译。
3. 裁掉被关闭的那些，但仅当它们能被静态证明是死代码时才在构建期裁剪，让生产打包产物保持小巧。

运行时过滤是唯一真理来源；构建期裁剪只是叠加在它之上的优化。

运行时始终是唯一真理

关掉构建插件，输出的日志完全一样。插件从不改变哪些日志可见——它只移除那些它能证明运行时本来也会关闭的调用。

三个组成部分

按需选用 Logaria 的任意部分：

• 精简的运行时 API（logaria）——创建日志器与配置可见性。
• 构建插件（logaria/plugin）——注入运行时配置，并可选地从生产打包产物移除被关闭的调用。
• 作用域核心 API（logaria/core）——让需要独立作用域的宿主集成不触碰默认作用域。

设计原则

几条选择让运行时保持小巧、插件保持保守：

• 小而可预测的运行时——一组纯函数与 5 个日志方法，没有传输器或格式化器需要配置。见 为什么是 Logaria。
• 运行时是真理——可见性由运行时过滤决定，插件只是优化。见 核心概念。
• 默认保守——只有当每一条静态事实都可证明时才裁剪某条调用；任何动态写法都会保留。见 为什么是 Logaria。
• 显式归属——只有一个默认作用域、恰好一个所有者；集成注册自己的作用域，而不是共享默认的。见 核心概念。
• 框架无关、类型安全——同一套 API 跑在 Node、浏览器与 CLI 中，公共类型由 logaria/types 暴露。见 为什么是 Logaria。

下一步

• 了解它解决的问题——为什么是 Logaria
• 安装并写出第一个日志器——快速开始
• 通过示例速览能力——特性一览
• 理解它背后的模型——核心概念