日志

func/log 为每次 CLI 调用创建独立的诊断日志。它适合保存排障信息，同时避免把内部细节混入正常 stdout。

注册并写入日志

通过 LogModule.register() 注册 Logger，然后在需要记录诊断信息的位置注入：

src/app.module.ts

Copy

import { Command, Handler, Module, createApp } from 'func'
import { Logger, LogModule } from 'func/log'

@Command('deploy')
export class DeployCommand {
  constructor(private readonly logger: Logger) {}

  @Handler()
  run() {
    this.logger.push('deploy started')
    this.logger.push({ target: 'production' })
  }
}

@Module({
  commands: [DeployCommand],
  imports: [LogModule.register()],
})
export class AppModule {}

const app = createApp(AppModule, { appName: 'ship' })

void app.bootstrap()

上例的日志目录为 ~/.ship/logs。应用名由 createApp({ appName }) 统一提供，func 只负责收集并透传；Log 会在 Logger Provider 初始化时验证应用名。每次调用拥有不同文件；文件名包含时间、进程 ID 和随机标识。

Logger.push(...data) 使用 Node.js console 的格式化语义，把参数组合成一条带 ISO 时间戳的文本记录。ANSI 控制字符会被移除，日志文件始终保存纯文本。

理解文件生命周期

创建 Logger 不会立即创建目录或文件。第一次成功调用 push 时才会创建日志文件，并在调用释放阶段关闭。

调用成功时不会额外输出日志位置。调用失败且已经写入日志时，释放阶段会向 stderr 提示文件路径：

Logs were written to "/Users/ada/.ship/logs/func-....log".

Logger.path 可以读取本次调用已经解析出的文件路径，即使文件尚未由第一次 push 创建。

控制大小和保留数量

默认单次调用最多写入 10 MiB，并保留最近 10 个 func 日志文件。可以在注册时调整：

TypeScript

Copy

LogModule.register({
  maxBytes: 2 * 1024 * 1024,
  maxFiles: 20,
})

超过大小限制后，本次调用的后续记录会被忽略，并最多输出一次警告。文件创建、写入、关闭或历史清理失败也不会替代原命令的执行结果。

历史清理只处理符合 func 日志命名格式的文件，不会删除同一目录中的其他文件。

API 速查