LogTape 是什么？

LogTape 是一个专为现代 JavaScript 生态系统设计的日志记录库。它以零依赖架构、跨 Node.js、Deno、Bun、浏览器和边缘函数的通用运行时支持，以及库优先的设计理念而脱颖而出，使库作者能够添加日志记录功能而不会给用户带来任何负担。当 LogTape 未配置时，日志调用几乎不会对性能产生影响，使其成为唯一真正无干扰的日志解决方案。

有关 LogTape 功能和理念的全面概述，请参阅我们的介绍指南。

里程碑成就

我们很高兴宣布 LogTape 1.0.0 的发布，这标志着该库开发的重要里程碑。此版本体现了我们对 API 稳定性和长期支持的承诺。1.0.0 版本表明 LogTape 的核心 API 现已稳定并可用于生产环境，未来的任何重大变更都将遵循语义化版本控制原则。

这一里程碑建立在数月的改进、社区反馈和实际使用的基础上，确立了 LogTape 作为 JavaScript 应用程序和库的成熟可靠的日志解决方案。

主要新功能

高性能日志基础设施

LogTape 1.0.0 引入了几个为高吞吐量生产环境设计的性能导向功能。新的非阻塞接收器选项允许控制台、流和文件接收器缓冲日志记录并异步刷新，防止日志操作阻塞应用程序的主线程。

import { configure, getConsoleSink } from "@logtape/logtape";

await configure({
  sinks: {
    console: getConsoleSink({ 
      nonBlocking: {
        bufferSize: 1000,
        flushInterval: 50
      }
    })
  },
  // ...
});

新的 fromAsyncSink() 函数提供了一种干净的方式来集成异步日志操作，同时保持 LogTape 的同步接收器接口。这使得将日志发送到远程服务器或数据库等场景成为可能，而不会阻塞您的应用程序。

import { fromAsyncSink } from "@logtape/logtape";

const webhookSink = fromAsyncSink(async (record) => {
  await fetch("https://logs.example.com", {
    method: "POST",
    body: JSON.stringify(record)
  });
});

对于文件操作，@logtape/file 包中的新 getStreamFileSink() 函数利用 Node.js PassThrough 流提供最佳 I/O 性能，并自动管理背压。

新的接收器集成

此版本通过两个主要的新接收器包显著扩展了 LogTape 的集成能力。@logtape/cloudwatch-logs 包支持与 AWS CloudWatch Logs 直接集成，具有智能批处理、指数退避重试策略，以及通过 JSON Lines 格式支持结构化日志记录。

import { getCloudWatchLogsSink } from "@logtape/cloudwatch-logs";

const sink = getCloudWatchLogsSink({
  logGroupName: "/aws/lambda/my-function",
  logStreamName: "my-stream",
  region: "us-east-1"
});

@logtape/windows-eventlog 包提供了原生 Windows 事件日志支持，具有跨 Deno、Node.js 和 Bun 的运行时兼容性。这种集成使用运行时优化的 FFI 实现以获得最大性能，同时保持适当的错误处理和资源清理。

美观的开发体验

新的 @logtape/pretty 包将控制台日志转变为专为本地开发设计的视觉吸引力体验。受 Signale 启发，它为每个日志级别提供彩色表情符号，智能类别截断以保留重要上下文，以及完美的列对齐，使日志易于扫描。

import { configure, getConsoleSink } from "@logtape/logtape";
import { prettyFormatter } from "@logtape/pretty";

await configure({
  sinks: {
    console: getConsoleSink({ formatter: prettyFormatter })
  },
  // ...
});

如上所示，美化格式化器支持真彩色终端，具有丰富的配色方案、可配置的图标，以及智能换行，即使对于长消息也能保持视觉一致性。

生态系统集成

也许最重要的是，LogTape 1.0.0 引入了适配器包，弥合了 LogTape 的库友好设计与现有日志基础设施之间的差距。@logtape/adaptor-winston 和 @logtape/adaptor-pino 包允许使用这些成熟日志库的应用程序无缝集成启用 LogTape 的库，而无需更改其现有设置。

// 使用 winston 快速设置
import "@logtape/adaptor-winston/install";

// 或使用自定义配置
import { install } from "@logtape/adaptor-winston";
import winston from "winston";

const logger = winston.createLogger({/* 您的配置 */});
install(logger);

这些适配器保留了 LogTape 的结构化日志功能，同时通过您首选的日志系统路由所有内容，使现有应用程序无障碍采用启用 LogTape 的库。

开发者体验增强

此版本包括几项提升开发者使用 LogTape 体验的改进。新的 getLogLevels() 函数提供对所有可用日志级别的编程访问，而 LogMethod 类型为日志方法提供更好的类型推断。

浏览器兼容性得到了改进，特别是对于 @logtape/otel 包，该包之前在浏览器环境中由于 Node.js 特定导入而存在问题。该包现在可以在所有 JavaScript 运行时中无缝工作，不会抛出模块解析错误。

重大变更和迁移指南

LogTape 1.0.0 包含一个值得注意的重大变更：移除了已弃用的 LoggerConfig.level 属性。该属性在 0.8.0 版本中被弃用，取而代之的是更具描述性的 LoggerConfig.lowestLevel 属性。

如果您的配置仍在使用旧属性，只需将其重命名：

// 之前（已弃用）
{ category: ["app"], level: "info", sinks: ["console"] }

// 之后
{ category: ["app"], lowestLevel: "info", sinks: ["console"] }

对于更复杂的过滤需求，请考虑使用 LoggerConfig.filters 选项，它提供更大的灵活性并支持从父记录器继承。

完整的包生态系统

LogTape 1.0.0 代表了一个全面包生态系统的集大成者，现在由 11 个专门解决日志基础设施不同方面的包组成。这种模块化方法允许您只安装所需的包，保持依赖占用最小，同时在需要时访问强大的日志功能。

包	JSR	npm	描述
@logtape/logtape	JSR	npm	核心日志功能
@logtape/adaptor-pino	JSR	npm	Pino 适配器
@logtape/adaptor-winston	JSR	npm	winston 适配器
@logtape/cloudwatch-logs	JSR	npm	AWS CloudWatch Logs 接收器
@logtape/file	JSR	npm	文件接收器
@logtape/otel	JSR	npm	OpenTelemetry 接收器
@logtape/pretty	JSR	npm	美观的文本格式化器
@logtape/redaction	JSR	npm	数据编辑
@logtape/sentry	JSR	npm	Sentry 接收器
@logtape/syslog	JSR	npm	Syslog 接收器
@logtape/windows-eventlog	JSR	npm	Windows 事件日志接收器

入门指南

无论您是 LogTape 新用户还是从之前版本升级，开始使用 1.0.0 都很简单。对于新项目，从简单的配置开始，然后逐步添加您需要的包和功能：

import { configure, getConsoleSink } from "@logtape/logtape";

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    { category: "my-app", lowestLevel: "info", sinks: ["console"] }
  ]
});

使用 winston 或 Pino 的现有应用程序可以通过安装适当的适配器立即从启用 LogTape 的库中受益。有关全面的迁移指导和详细的功能文档，请访问我们的文档网站。

1.0.0 版本不仅仅代表一个版本号，更代表着对生产应用程序所需稳定性和成熟度的承诺。我们很期待看到您用 LogTape 构建的项目。