Terser 多文件压缩导致变量重复声明的线上事故复盘与最终解决方案

在前端工程化中，Terser 是最常用的 JavaScript 压缩工具之一。它体积小、压缩率高、混淆能力强，是许多构建链路的默认选择。然而在一次看似普通的多文件压缩发布中，我遇到了一次非常隐蔽、却极具代表性的线上问题： 页面加载多个独立压缩后的 JS 文件，出现变量重复声明冲突，导致功能异常。

这篇文章完整记录问题的出现、原因定位以及最终稳定落地的解决方案。

一、问题现象

项目中有多个业务脚本文件：

/static/js/user.js
/static/js/config.js
/static/js/report.js

它们在页面中通过多个 <script> 标签加载，逻辑彼此独立。

上线前，我对每个文件单独使用 Terser 进行压缩：

terser user.js   -o user.min.js
terser config.js -o config.min.js
terser report.js -o report.min.js

上线后，部分页面脚本执行异常，控制台报错：

Uncaught SyntaxError: Identifier 'a' has already been declared

刷新偶现、顺序变化时又消失，极具迷惑性。

二、问题排查

首先确认源码本身不存在重复变量声明。未压缩版本运行完全正常。问题只在压缩后出现。

打开压缩后的文件，发现每个文件内部的局部变量都被混淆成了极短命名，例如：

user.min.js

(()=>{let a=getUser();console.log(a)})()

config.min.js

(()=>{let a=getConfig();console.log(a)})()

当多个脚本同时加载时， 混淆后的变量名在同一执行上下文中重复出现 ，导致 JavaScript 引擎报重复声明错误。

问题到这里已经非常明确： 多文件独立压缩 → 各自产生相同混淆变量名 → 同一页面执行 → 作用域冲突。

三、根本原因

Terser 在独立压缩每个文件时，并不知道这些文件将会在同一页面运行。因此它会从 a,b,c,d... 开始重新分配变量名。

如果原文件没有严格的独立作用域隔离（或构建参数开启了 toplevel 混淆），这些变量会进入共享执行环境，最终造成冲突。

这类问题在小型项目中很常见，但在大型多脚本页面中尤为致命，因为它往往只在特定加载顺序下触发。

四、最终解决方案：闭包隔离（IIFE）

为了彻底解决作用域污染问题，并保持多文件独立发布的构建方式，我采用了最稳定、最通用的方案：

为每个脚本文件添加立即执行函数包裹（IIFE），形成独立私有作用域。

改造方式非常直接：

改造前

let user = getUser()
console.log(user)

改造后

;(function(){
  let user = getUser()
  console.log(user)
})()

这个结构会在文件加载时立即执行，同时生成一个独立作用域，使内部变量无法泄露到全局执行环境。

压缩后变为：

(()=>{let a=getUser();console.log(a)})()

即便多个文件都被混淆成 a ，它们也各自存在于独立函数作用域中，互不影响。

五、结果验证

改造后：

• 多文件独立压缩
• 多 <script> 同时加载
• 多次刷新测试
• 不同加载顺序测试

所有变量冲突问题彻底消失，线上运行稳定。

无需调整构建流程，无需引入额外打包器，无需改变发布策略。

问题完全闭环解决。

六、方案价值

这个方案具备几个关键优势：

• 不依赖构建工具
• 不改变部署结构
• 不影响运行性能
• 完全杜绝变量泄漏
• 对旧项目改造成本极低

对于仍然采用“多脚本直出页面”的系统，这是最稳妥、最工程化的解决方式。

七、总结

这次问题表面上是 Terser 混淆冲突，实质上是 作用域隔离缺失 导致的运行时污染。最终采用 IIFE 闭包隔离方案，为每个文件提供私有执行空间，使独立压缩与多脚本共存成为安全组合。问题彻底解决，构建链路保持简洁，线上运行稳定。

到这里，这个线上事故正式结案。