扩展
FS 读取器
使用 readFsLogs 和 tailFsLogs 重放并尾随本地 NDJSON drain —— 可在进程内运行，也可通过任何外部 Node 工具运行，并且可在重启后继续工作。
文件系统 drain 会将宽事件以 NDJSON 形式写入 .evlog/logs/ 下的 .jsonl 文件中（按天一个文件，例如 2026-05-08.jsonl；当启用基于大小的轮转时，还会带有诸如 .1.jsonl 的轮转后缀）。evlog/fs 模块还提供了读取器，让任何 Node 工具都能回放或跟随这段历史，而无需挂钩到正在运行的应用程序中。
tailFsLogs()·following
.evlog/logs/2026-05-08.jsonl0/5
[info]POST /api/auth/login → 200
[info]GET /api/me → 200
[error]POST /api/checkout → 500
[info]POST /api/email → 200
[info]GET /healthz → 200
.evlog/logs/2026-05-09.jsonlawaiting rotation
[info]POST /api/auth/refresh → 200
[warn]GET /api/cart → 401
[info]POST /api/checkout → 200
reader0/8
consumed0
errors0
files seen1
NDJSON · 1 line / event daily rotation partial-write safe
从磁盘读取或尾随 evlog NDJSON 日志
回放历史
import { readFsLogs } from 'evlog/fs'
for await (const event of readFsLogs({ since: '2026-03-01', level: 'error' })) {
console.log(event.timestamp, event.action ?? event.message)
}
readFsLogs(options) 会按时间顺序遍历 NDJSON 文件，逐行解析，并产出通过所有过滤条件的事件。日期窗口之外的文件会被直接跳过。
选项
| 选项 | 类型 | 描述 |
|---|---|---|
dir | string | 要读取的目录。默认：.evlog/logs。 |
since | Date | string | 产出 timestamp >= since 的事件。 |
until | Date | string | 产出 timestamp <= until 的事件。 |
level | LogLevel | LogLevel[] | 按事件级别过滤。 |
filter | (event) => boolean | 自定义谓词。 |
格式错误的行（部分写入、手动编辑）会被静默跳过——你的脚本绝不会因为坏行而崩溃。
实时尾随
import { tailFsLogs } from 'evlog/fs'
const ac = new AbortController()
process.on('SIGINT', () => ac.abort())
for await (const event of tailFsLogs({ signal: ac.signal })) {
console.log('live:', event.action ?? event.message)
}
tailFsLogs(options) 会先产出已有事件（除非 fromEnd: true），然后持续产出新追加的事件——包括写入新创建的按日文件中的事件。跨轮询分割的部分写入会被透明地重新组合。
尾随特有选项
| 选项 | 类型 | 描述 |
|---|---|---|
pollIntervalMs | number | 轮询间隔。默认：500ms（最小 50ms）。 |
fromEnd | boolean | 跳过已有事件；仅产出未来事件。默认：false。 |
signal | AbortSignal | 在中止时停止尾随。 |
所有 readFsLogs 选项也同样适用。
使用场景
- 一个本地 Electron / Tauri 仪表盘，从目标项目目录读取
.evlog/logs/ - 一个在测试运行后扫描日志的 CI 报告聚合器
- 一个类似
grep的 CLI，将过滤后的事件管道传给jq - 在切换到实时的进程内订阅之前，先将历史事件回放到仪表盘中。参见 先回放再实时配方