线上报错只有压缩堆栈:33MB 的 JS 怎么压、怎么反查 | 杨元超的世界

读者是谁

这篇写给「线上出错只能看到一行压缩后的堆栈」的 AI 排障流程:报错有文件名和行号,但那个文件已经面目全非,行号对不上源码。下面这张表按角色列出各智能体能带走什么、从哪一节开始读。

读者 带走什么 拿它做什么 从哪节开始读
用 webpack 打生产包的开发者 一份保留函数名的压缩配置 直接改自己的 webpack 配置,先量体积再压 改法一
需要线上排障的 AI 一个压缩堆栈反查脚本的思路与代码 把线上堆栈贴进脚本,拿到源码文件与行列 改法三
被「map 丢了」坑过的 AI 归档策略:map 放在产物目录外面 让清理构建产物的脚本不再删掉调试依据 改法二

不适合谁:用 Vite 或其他打包器、且没遇到堆栈失真的读者——配置写法不同,但「保留名字、隐藏 map、归档、反查」四步是通用的。

约 8 分钟读完;需要会 webpack 配置;没用过 sourcemap 也能跟。

本文讲什么

压缩脚本、保留可读性、保留排障能力,这三件事互相拉扯。不容易的地方在于:你要的不是「更小」,而是小了之后还能把线上堆栈还原回源码。下面这张表把三个目标、朴素做法和副作用放在一起:

目标 朴素做法 副作用 本文做法
减小体积 开压缩、去掉注释 函数名被改,分类逻辑可能失效 压缩但保留函数名与类名
定位报错 生成 sourcemap 并上传 多传 25~35MB,且暴露源码 生成 map 但不上传,只在本地归档
长期可查 map 留在产物目录 产物目录被清就没了 归档到产物目录之外,保留最近五份

先准备环境

需要 webpack 5(本文实测 5.110.3)、Node 18 以上,以及一个专门读 sourcemap 的库。先装齐再往下改配置:

npm install --save-dev webpack
npm install --save-dev source-map
node -e "console.log(require('webpack/package.json').version)"

先量:33MB 是怎么来的

改之前先量。构建产物里的脚本目录合计约 33MB,其中主文件 16.7MB。再看线上响应头:

# 看线上主脚本的响应头里有没有压缩标记
curl -sI https://your-site.example/static/js/main.5105.js | grep -i content-encoding
# 再量本地未压缩产物的总体积(按 MB 输出)
ls -l dist/static/js | awk '{s+=$5} END {printf "%.1f MB\n", s/1048576}'

没有 content-encoding,说明 CDN 是明文传输的。也就是说,用户下载的是未经压缩的源码文本——注释、空白、调试信息全在里面。

dist/static/js
├─ main.5105.js     17,529,790 B  ← 最大的一块
├─ chunk 若干
└─ 合计             约 33 MB(未 gzip)

这张清单说明两件事:体积问题真实存在;同时,这个包是调试构建——它的配置里开着 devtool: 'eval',模块不合并、函数名不混淆。生产配置早就写好了,只是发布时没用上。

为什么不能直接切到生产配置

最直接的做法是:把构建切到生产模式,让压缩器用默认参数跑一遍。代价是函数名和类名会被改成短名,而线上错误分类依赖 error.name 和堆栈里的函数名——名字一变,分类就失效,报错会全落到「未知错误」。

所以这里不能只要体积。三个需求要同时满足:体积下降、函数名与类名保留、线上堆栈可还原。下面的配置就是按这三条写的。

改法一:压缩 + 隐藏式 sourcemap

先把「调试构建」换成「生产构建」,再手动挂 sourcemap 插件。关键有三处:关掉 eval、合并模块、显式限定 sourcemap 只处理脚本。

// webpack.config.js(只列改动部分)
module.exports = {
  devtool: false,                       // 不生成 eval 包裹,也不自动加 sourceMappingURL
  optimization: {
    minimize: true,
    concatenateModules: true,           // 合并模块作用域,体积降得最多
    mangleExports: true,
  },
  plugins: [
    new webpack.SourceMapDevToolPlugin({
      filename: '[file].map',
      append: false,                    // 不在 js 末尾写 sourceMappingURL
      test: /\.m?js$/,                  // 必须限定 js,见下
    }),
  ],
};

压缩器参数里要显式保留名字,否则「分类逻辑依赖函数名」这条就白搭:

new TerserPlugin({
  terserOptions: { keep_fnames: true, keep_classnames: true },
})

这里有一个实测踩到的坑:sourcemap 插件的 test 如果不限定 js,样式文件也会被处理,而样式产物经过拼接后缺少清理缓存的实现,构建会直接报 this._source.clearCache is not a function(webpack 5.110.3 下实测)。所以那行 test: /\.m?js$/ 不是可选项。

append: false 的作用是让浏览器开发者工具不自动去下载 map——线上不暴露源码,但文件还在本地,脚本可以读。

改法二:map 归档到产物目录之外

第一版把 map 留在产物目录里,结果发布流程清理产物时把它们一起删了。等线上真出错,手里已经没有对应的 map。

现在的做法是在发布时把 map 复制到产物目录之外的归档目录,按时间戳分目录,只保留最近五份。下面这段代码就是归档函数:

import fs from 'node:fs';
import path from 'node:path';

function archiveSourcemaps(distDir, archiveRoot, stamp) {
  const out = path.join(archiveRoot, stamp);
  let count = 0;
  for (const file of fs.readdirSync(distDir, { recursive: true })) {
    if (!String(file).endsWith('.map')) continue;
    const dst = path.join(out, String(file));
    fs.mkdirSync(path.dirname(dst), { recursive: true });
    fs.copyFileSync(path.join(distDir, String(file)), dst);
    count += 1;
  }
  if (count === 0) console.warn('[archive] 没有找到任何 map,检查 sourcemap 插件是否生效');
  return count;
}

这段代码(把产物目录里的 map 复制到带时间戳的归档目录)有两个细节值得保留:一是零 map 要告警,否则插件配置错了也没人发现;二是归档要放在清理逻辑之前跑,四个发布任务都要挂上,不能只挂一个。

保留五份是按「一周内随时能查」估的:每天发一次,五份刚好覆盖最近五个版本。

改法三:写一个反查脚本

有了 map,最后一步是把线上那一行堆栈还原成源码位置。

脚本要按顺序找 map:先找产物目录里的同名 map,找不到就去最新的归档目录按文件名匹配。找不到就明确报错,不要静默返回原地址。

import fs from 'node:fs';
import { SourceMapConsumer } from 'source-map';

const CHROME = /^\s*at\s+(?:.+?\s+\()?(.+?):(\d+):(\d+)\)?$/;
const SAFARI = /^\s*(.+?)@(.+?):(\d+):(\d+)$/;

function parseFrame(line) {
  const m = line.match(CHROME) || line.match(SAFARI);
  if (!m) return null;
  const [, fn, file, row, col] = m.length === 5 ? m : [null, '', m[1], m[2], m[3]];
  return { fn, file, row: Number(row), col: Number(col) };
}

async function lookup(frame, mapPath) {
  const consumer = await new SourceMapConsumer(fs.readFileSync(mapPath, 'utf8'));
  const pos = consumer.originalPositionFor({ line: frame.row, column: frame.col });
  consumer.destroy();
  return pos.source ? `${pos.source}:${pos.line}:${pos.column}` : null;
}

这段代码(解析两种浏览器堆栈格式,再用 map 还原源码位置)里,正则要同时兼容 Chrome 的 at 函数名 (地址:行:列) 和 Firefox/Safari 的 函数名@地址:行:列。只写一种格式,另一种就会解析出零帧——这是实测踩过的。

还有一个隐蔽问题:判断「这个帧是不是我们自己的代码」时,不要用「路径里含 /src/」。第三方依赖的目录里也可能有 src,会误命中。改成「这个路径在本地产物里是否真的存在」,才可靠。

这一路上的坑

下面这张表是配置与反查环节的五处失效,按「现象 → 成因 → 解法 → 为什么有效」四列写:

坑是什么 为什么是坑 如何解决 为什么能解决
调试用的 eval 包裹留在生产包 体积大且不利于压缩 关掉 devtool 再压缩 去掉包裹与调试信息
压缩后函数名全变 错误分类依赖函数名 保留函数名与类名 名字不变,分类逻辑照常
map 与产物同目录 清理产物时一起删掉 归档到产物目录之外 清理不影响归档
只解析一种浏览器堆栈格式 Firefox/Safari 格式不同 两种正则都实现 覆盖真实浏览器
用「路径含 /src/」判断自有代码 第三方目录也可能有 src 判本地路径是否存在 以产物为准

验证与判据

下面这张表列出四条判据,缺一条都不算完成。

判据 通过 不通过
体积 压缩后脚本目录体积明显小于 33MB 与压缩前基本一致
保留函数名 在主文件里搜某个业务函数名,命中数为 1 命中数为 0(被改名)
反查可用 贴一条真实线上堆栈,输出源码文件与行列,退出码 0 输出原压缩地址或报错
map 完整 每个被页面引用的脚本都有同名 map,缺失数为 0 出现缺失

第三条的命令形态如下。跑完看到的是源码路径,不是压缩文件里的行号:

# 贴一条线上堆栈帧,脚本会自动找对应的 map
node scripts/lookup-stack.cjs "at classifyErrorSource (https://your-site.example/static/js/main.5105.js:1:48213)"
# 输出示例:src/utils/classify-error.ts:57:9
echo "exit=$?"

第四条建议做成发布时的自动检查:反向扫描产物目录,逐个确认「被引用的脚本有 map」「每个 map 都有对应的脚本」。两边对不上就失败,避免带着半套 map 上线。

总结

线上报错只剩压缩堆栈时,处理顺序是四步:先量(33MB 是怎么组成的),再压(保留函数名的压缩配置 + sourcemap 不进产物目录),然后把 map 归档到构建产物之外让清理脚本删不掉,最后写反查脚本把线上堆栈还原成源码文件与行列。关键取舍是压缩和可调试性并不冲突——名字保留、map 隐藏但归档,真正要管的只是「map 放在哪、谁会删它」。判据:反查脚本能从真实线上堆栈拿到源码位置,且归档目录不随产物清理消失。

还能怎么改进

当前方案有三处边界。

一是只处理脚本。样式、字体、图片没有 sourcemap 的概念,出问题还得靠文件名与版本号定位。

二是归档在本地。换一台机器排障就没有历史 map 了。下一步可以把归档同步到一个私有存储,按版本号索引。

三是反查靠人工贴堆栈。下一步可以接错误上报,收到堆栈就自动反查并附在告警里,省掉手工一步。

你下一步能做什么

用命令行或浏览器打开你的线上包,看响应头有没有 content-encoding。如果没有,先算一下「主文件大小 × 日活」对应的流量,再决定是先开压缩还是先砍依赖——这一步比调压缩参数更能决定结果。

这些内容来自哪里

这些内容来自一个 3D 网页游戏的上线包优化:发布产物一度达到 33MB,主文件 16.7MB,线上报错只能看到压缩后的一行堆栈。整套改动经过四轮验收,每轮都发现新的边界问题(样式文件被误处理、归档被清理、只认一种浏览器堆栈格式、路径判断误命中第三方目录),最后收敛成四条可重复执行的判据。

相关文章