使用 grunt 注入结构化日志并关联 traceId - 问题详情 - 创脉思

解读

在国内一线/二线互联网公司的前端面试中，“构建层可观测性” 已成为区分初中高级的重要考点。
题目表面问“如何在 Grunt 里打日志”，实质考察三点：

是否理解**“结构化日志”（JSON 格式、统一字段、可检索）与“traceId”**（一次请求/一次构建的全链路唯一标识）的价值；
能否在 Grunt 的**“任务级、插件级、文件级”三个切面把 traceId 无侵入地注入，并保证多任务并发时上下文不串**；
是否知道把日志**落盘到本地文件 + 实时吐到日志平台（如阿里云 SLS、腾讯 CLS）**的完整闭环，方便后续排查构建失败、性能劣化。

知识点

Grunt 事件流：grunt.task.run、grunt.event.on('task_start'/'task_error')、grunt.log 的底层是 grunt.log.write，可拦截。
AsyncHook & continuation-local-storage：Node 8 以前用 continuation-local-storage，Node 12+ 用 AsyncLocalStorage 做异步上下文传递，保证 traceId 在插件回调里不丢。
结构化日志字段规范：timestamp、level、traceId、spanId、task、plugin、file、line、message、stack、buildEnv、gitCommit、duration。
Grunt 插件开发范式：通过 grunt.registerMultiTask 包装原插件，在 wrapper 里注入日志逻辑，对业务 Gruntfile 零改动。
日志不落地的风险：国内合规要求**“构建日志至少保留 6 个月”**，必须配置 logrotate 与冷热分层。
性能红线：注入逻辑不能拖慢整体构建，每 10k 文件增加耗时 < 2%，否则会被 CI 门禁打回。

答案

在项目根目录新建 grunt-trace-log.js 工具模块：
a) 使用 Node AsyncLocalStorage 实例化一个全局 store；
b) 暴露 runWithTrace(fn, traceId) 包装函数，把 traceId 写进异步上下文；
c) 提供 getLogger(taskName) 返回带 traceId 的 winston 实例，格式为
{timestamp,level,traceId,task,file,message}。

在 Gruntfile 最顶部引入该模块，并在 module.exports = function (grunt) { … } 的第一行生成一次构建级别的 traceId（可用 CI_PIPELINE_ID 或 uuid.v4()），随后

grunt.registerTask('build', function() {
  const done = this.async();
  runWithTrace(() => {
    grunt.task.run(['clean', 'eslint', 'webpack', 'uglify']);
    done();
  }, traceId);
});

对核心插件做无侵入包装：
以 grunt-contrib-uglify 为例，新建 tasks/grunt-trace-uglify.js：

module.exports = function(grunt) {
  const original = require('grunt-contrib-uglify/tasks/uglify');
  grunt.registerMultiTask('traceUglify', function() {
    const logger = getLogger('uglify');
    const start = Date.now();
    logger.info({event:'start', files:this.filesSrc.length});
    try {
      original.call(this);
      logger.info({event:'end', duration:Date.now()-start});
    } catch(e) {
      logger.error({event:'error', stack:e.stack});
      throw e;
    }
  });
};

在 Gruntfile 里用 traceUglify 替换原来的 uglify 任务即可。

日志采集与上报：
a) 本地以天为单位落盘到 logs/${traceId}.log，配置 logrotate 按 100 MB 切割；
b) 在 CI 的 after_script 阶段使用阿里云 SLS CLI 上传：
```
aliyunlog log create_log_file --project=front-build --logstore=grunt --topic=${CI_PIPELINE_ID} --filename=logs/${traceId}.log
```
c) 日志平台索引字段必须包含 traceId，方便按一次构建聚合。
验证：
本地执行 grunt build --trace-log-level=debug，观察
- 每个子任务日志均带同一 traceId；
- 并发任务（如 grunt-concurrent）下 traceId 不串；
- 构建失败时，SLS 侧能秒级定位到具体插件、文件、堆栈。

拓展思考

多构建机场景：若使用 Kubernetes 动态 Pod，需把 traceId 注入到 Pod 的环境变量，并在初始化容器里预写 logs/.traceId 文件，保证 Pod 重启后仍能续接上下文。
与前端运行时 traceId 打通：在构建阶段把 traceId 写入 window.__BUILD_TRACE_ID__，线上报错日志通过 Source-map 自动关联到对应构建版本，实现“构建-运行”全链路追踪。
性能精细化：在日志里增加 phase 字段（parse、transform、emit、write），结合阿里云 SLS 的 SQL 聚合，可绘制“构建火焰图”，量化每个插件的耗时占比，为后续升级 Webpack/Vite 提供数据依据。