JavaScript打包工具常见问题排查指南

前端开发中，ref="/tag/137/" style="color:#E3A3CF;font-weight:bold;">JavaScript打包工具像Webpack、Vite、Rollup这些家伙几乎天天打交道。项目一跑起来，控制台突然报错，页面白屏，八成是打包环节出了岔子。很多人第一反应是查代码逻辑，其实问题可能出在打包配置上。

依赖装了却说模块找不到？

你npm install完一个库，import的时候却提示 Module not found。这种情况很常见，尤其在使用非主流库或私有包时。先检查node_modules里有没有这个包，没有就是安装失败；有的话，可能是打包工具没正确解析路径。比如Webpack需要配置resolve.modules或alias：

module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
};

漏了这一步，相对路径引用就容易乱套。

打包后文件太大，页面加载慢得像蜗牛

一个js文件几MB，用户点开页面就得等十秒，体验直接崩盘。这时候得看是不是把所有依赖全打进一个包了。比如React、Lodash这种大块头，应该考虑代码分割（code splitting）。用动态import拆分路由：

const About = () => import('./pages/About');

再配合Webpack的splitChunks，把公共依赖单独抽出来，首页加载速度立马提升。

热更新失灵，改一行代码要重启服务

开发时最烦的就是改完保存，浏览器不自动刷新。Vite一般不会这样，但Webpack配置不当就容易出问题。检查devServer.watchFiles有没有漏掉关键目录，或者node_modules变动太多导致监听卡住。可以加个配置强制监听：

devServer: {
  watchOptions: {
    ignored: /node_modules/,
    poll: 1000 // 启用轮询，适合某些虚拟机环境
  }
}

Tree Shaking没生效，无用代码还在包里

你用了ES6模块语法，也删了没用的函数，但打包结果还是臃肿。问题可能出在第三方库本身——如果它发布的是CommonJS格式（require/module.exports），Tree Shaking基本失效。查看package.json里的module字段，优先选提供ESM版本的库。自己的代码也要避免混合导出：

// 别这么写
exports.default = Component;
exports.someUtil = util;

// 改成
export default Component;
export { util };

构建报错信息看不懂，一行红字堆满屏

尤其是TypeScript项目，加上Babel、PostCSS各种插件，一出错就是几十行警告。这时候别慌，从上往下看，第一个报错才是根因。后面的往往是连锁反应。可以用--display-error-details参数让Webpack输出更详细的信息。Vite的话看浏览器控制台的错误堆栈更直观，它通常能定位到具体哪一行。

实际排错时，建议一步步来：先把插件全关掉，只留基础配置，看能不能跑通；再逐个开启，找到引发问题的那个。别一上来就抄别人的复杂配置，适配不好反而添乱。