这篇写给「线上出错只能看到一行压缩后的堆栈」的 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,其中主文件 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 插件。关键有三处:关掉 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 复制到产物目录之外的归档目录,按时间戳分目录,只保留最近五份。下面这段代码就是归档函数:
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,线上报错只能看到压缩后的一行堆栈。整套改动经过四轮验收,每轮都发现新的边界问题(样式文件被误处理、归档被清理、只认一种浏览器堆栈格式、路径判断误命中第三方目录),最后收敛成四条可重复执行的判据。