logcli

一个简单的日志写入 CLI，支持可变参数、环境变量配置，以及按天+按文件大小滚动。

功能特性

• 日志格式：时间戳|参数1|参数2|...
• 支持可变参数输入：logcli [args...]
• 支持参数覆盖：
  • --dir <path> 日志目录
  • --file <name> 基础文件名
• 支持环境变量：
  • LOGCLI_DIR
  • LOGCLI_FILE
  • LOGCLI_MAX_SIZE（字节）
• 文件滚动策略：
  • 按天分文件
  • 按大小阈值切分片

使用要求

• Node.js >=18

安装与运行

在 logcli 目录执行：

npm install

本地直接运行：

node bin/logcli.js hello world

如果要全局命令调试：

npm link
logcli hello world

命令参数

logcli [args...] [--dir <path>] [--file <name>]

• args...：要写入日志的可变参数
• --dir：日志目录（优先级最高）
• --file：基础文件名（优先级最高）

配置优先级

CLI 参数 > 环境变量 > 默认值

默认值：

• dir: ~/.logcli/logs
• file: app.log
• maxSize: 10485760（10MB）

环境变量

• LOGCLI_DIR：日志目录
• LOGCLI_FILE：基础文件名（仅文件名，不能带路径分隔符）
• LOGCLI_MAX_SIZE：单日志文件最大字节数，超过则滚动到下一个分片

示例：

LOGCLI_DIR=/tmp/logs LOGCLI_FILE=order.log LOGCLI_MAX_SIZE=1048576 node bin/logcli.js create success

日志文件命名规则

基础文件名假设为 app.log，实际写入文件为：

app-YYYY-MM-DD.N.log

• YYYY-MM-DD：当天日期
• N：当天分片号，从 0 开始

示例：

• app-2026-04-13.0.log
• app-2026-04-13.1.log

写入示例

node bin/logcli.js login success user123 --dir /tmp/logcli --file app.log

日志文件中的一行示例：

2026-04-13T11:35:05.132Z|login|success|user123

特殊字符处理

参数会做最小转义，避免破坏 | 分隔格式：

• \ -> \\
• | -> \|
• \r、\n -> 空格

错误处理

失败时：

• 错误信息输出到 stderr
• 进程退出码为 1

常见错误：权限不足、磁盘空间不足、路径不存在、参数非法。

测试

在仓库根目录执行：

npm test

发布流程（REL-02）

以下流程用于将 @bjtufang/logcli 发布到 npm（需要先完成 npm login）。

1) 发布前检查

在仓库根目录执行：

npm test
npm --prefix logcli run pack:check

确认测试通过且打包内容符合预期。

2) 版本号管理

在 logcli 目录执行（按语义化版本）：

npm version patch   # bugfix
# 或
npm version minor   # backward-compatible feature
# 或
npm version major   # breaking changes

3) 发布到 npm

在 logcli 目录执行：

npm publish --access public

4) 发布后验证

npm view @bjtufang/logcli version
npm i -g @bjtufang/logcli
logcli --help

5) 版本修复建议

• 如果发布内容有问题，建议发布新版本修复（不要覆盖已发布版本）。
• 若某个版本不推荐使用，可执行：

npm deprecate @bjtufang/logcli@<version> "reason"

或在 logcli 目录执行：

npm test