解决Webpack打包报错：Cannot assign to read only property ‘exports’ 深度解析与实战指南

在前端工程化实践中，模块打包工具（如Webpack）与代码编译工具（如Babel）的结合使用极大地提升了开发效率。然而，开发者有时会遭遇一种令人费解的窘境：项目在本地开发环境（例如执行 npm run dev）运行一切如常，但一旦执行生产环境构建（如 npm run build）并将产物部署到线上后，浏览器控制台却直接抛出致命错误：TypeError: Cannot assign to read only property 'exports' of object '#<Object>'。

本文将围绕这一经典报错展开深度剖析，从模块系统底层机制出发，提供多视角的排查思路与落地的解决方案，帮助开发者彻底根除这一构建顽疾。

一、报错背景与现象特征

近期，某基于早期前端框架（如Vue2结合Webpack构建）的老项目在生产环境突发异常。该项目在很长一段时间内未做改动，却在某次访问中突然出现部分页面无法加载的情况。通过抓取线上控制台的报错信息，我们可以清晰地看到如下错误调用栈：

TypeError: Cannot assign to read only property 'exports' of object '#<Object>'
    at Object.<anonymous> (0.d97ee341e9f7c8f3e805.js:1:14033)
    at 16Wf (0.d97ee341e9f7c8f3e805.js:1:16662)
    at n (manifest.83cbbf59a618d5d725c4.js:1:101)
    ...

现象特征总结：

1. 环境差异明显：本地开发环境无任何异常，仅在生产环境构建后出现问题。
2. 报错位置隐蔽：错误堆栈均指向经过压缩混淆的打包产物（如带有hash值的chunk文件），难以直接定位到具体源码。
3. 突发性强：往往在项目平稳运行很久后突然爆发，可能与某次新引入的第三方依赖库或微小配置变更有关。

二、核心原因剖析：模块系统的世纪冲突

要理解这个报错，必须深入到JavaScript的模块化规范层面。当前主流存在两种模块系统：CommonJS（CJS，使用 require/module.exports）与ES Module（ESM，使用 import/export）。

当Webpack与Babel协同工作时，它们通常会将ESM模块编译保留或转换为CJS。然而，在同一个模块文件中混用这两种规范，就会触发不可预期的错误。

具体到本报错：Cannot assign to read only property 'exports'。其底层逻辑在于，当Babel等编译工具将ESM的 import/export 转换为符合严格模式的代码时，如果Webpack又以ESM模式去处理该文件，Webpack会通过 Object.defineProperty 将 module.exports 对象冻结或设为只读（read only），以强制执行ESM的静态特性。此时，如果代码中（或引入的老旧第三方库中）又使用了CommonJS的 module.exports = ... 进行赋值，JavaScript引擎就会抛出尝试给只读属性赋值的类型错误。

本地开发环境之所以不报错，通常是因为开发模式下代码未经过压缩，Webpack对模块系统的校验与干预较宽松，或者特定的构建优化插件未启用，从而掩盖了潜在的冲突。

三、实战解决方案与落地步骤

针对上述问题，我们可以从构建配置与源码排查两个维度进行修复。建议按照以下方案的优先级依次尝试。

方案一：修正Babel编译配置（推荐首选）

确保Babel在编译JavaScript时，正确处理模块化语法，避免将ESM降级为CommonJS时与Webpack的模块处理产生冲突。检查项目根目录下的 .babelrc 或 babel.config.js 文件。

一个标准的、与现代Webpack兼容的Babel配置应确保 @babel/preset-env 的 modules 选项设置为 false。这会告诉Babel：“不要管模块语法，将其原样保留交由Webpack处理”。

{
  "presets": [
    [
      "env", 
      {
        "modules": false,
        "targets": {
          "browsers": ["> 1%", "last 2 versions", "not ie <= 8"]
        }
      }
    ],
    "stage-2"
  ],
  "plugins": ["transform-runtime"]
}

注意：如果项目中没有相关配置文件，需手动创建并确保 modules: false 生效。这能解决绝大多数因Babel错误降级引发的赋值异常。

方案二：调整Webpack构建规则配置

如果Babel配置无误，问题可能出在Webpack打包时对不同类型JS文件的处理规则缺失。特别是在生产环境构建配置（如 build/webpack.prod.conf.js）中，需要确保所有的 .js 文件都经过Babel-loader的正确处理。

在Webpack的 module.rules 中补充或修正如下规则：

module: {
  rules: [
    {
      test: /\.js$/,
      loader: 'babel-loader',
      exclude: /(node_modules|bower_components)/, // 排除第三方依赖，避免过度编译
      options: {
        presets: [
          ['env', { modules: false }] // 再次确保预设配置中模块保持原样
        ]
      }
    }
  ]
}

这段配置确保了项目自身的业务代码在打包时遵循统一的模块化标准，避免了部分文件被错误解析。

方案三：精准定位并修复源码层面的混用

如果上述配置方案均未能奏效，说明问题出在具体的源码文件中（大概率是新引入的某个第三方库或老旧的公共JS文件）。此时需要精准定位是哪个文件混用了模块语法。

定位思路：

1. 利用报错堆栈中提供的chunk文件名（如 0.d97ee341e9f7c8f3e805.js），在Webpack的构建配置中开启更详细的 sourceMap 或使用构建分析工具，逆向推导该chunk包含哪些源文件。
2. 也可以借助智能编程工具或大模型，将报错上下文输入，辅助分析可能存在语法冲突的代码块。

修复策略：
一旦定位到具体文件，严格执行单一模块规范：

• 如果文件使用了 import/export，则坚决删除其中的 module.exports = ...。
• 如果是老旧的CommonJS文件，应统一使用 require() 和 module.exports，确保不要在顶部混入 import 语法。

四、预防与工程化最佳实践

为了在后续的迭代中避免此类问题再次发生，建议在前端工程中落实以下最佳实践：

1. 统一模块化规范：整个项目（包括工具函数、业务逻辑、第三方定制库）应严格统一使用ES Module规范，彻底摒弃CommonJS写法。
2. 完善静态代码检测：引入代码检查工具（如ESLint），开启 no-commonjs 或相关混合使用检测规则，在开发阶段就将混用语法拦截在提交前。
3. 本地模拟生产构建：修改项目脚本，在本地开发流程中加入模拟生产打包的验证环节。每次提交代码前执行一次完整的构建，并运行基础冒烟测试，防止“本地能跑线上崩”的尴尬。
4. 依赖库审查机制：在引入新的第三方依赖时，关注其打包产物是否兼容当前的构建体系，避免引入存在历史包袱的CommonJS库导致全局污染。

五、总结

TypeError: Cannot assign to read only property 'exports' 表面上是一个运行时的类型错误，实质上是前端工程化演进过程中，新旧模块化规范交替冲突在打包工具上的集中爆发。通过合理配置Babel的 modules: false、完善Webpack的loader规则，以及严格规范源码层面的语法书写，我们不仅能解决眼前的构建报错，更能从长远提升前端工程体系的健壮性与可维护性。