Vite构建乱序打包引发Uncaught ReferenceError错误，寻求解决方案

核心原因 #

这个错误本质是Rollup（Vite底层打包工具）的模块排序逻辑和Webpack存在差异，导致某个模块在其依赖的变量/模块定义完成前就被执行了。断点等待后能恢复，和文件加载耗时无关——单文件是一次性加载的，只是执行顺序出了问题，断点期间浏览器完成了整个文件的解析，变量已完成初始化。

具体解决方案 #

1. 强制调整模块执行顺序 #

在vite.config.js中使用rollup-plugin-order插件，把被依赖的模块放在引用它的模块前面：

// vite.config.js
import { defineConfig } from 'vite';
import order from 'rollup-plugin-order';

export default defineConfig({
  build: {
    rollupOptions: {
      plugins: [
        order([
          // 替换为你找到的被依赖模块路径（比如dispatch-handler.js所在路径）
          'src/utils/dispatch-handler.js',
          // 替换为引用该模块的文件路径（比如index.tsx）
          'src/index.tsx'
        ])
      ]
    }
  }
});

如果不确定路径，直接查看打包后的大文件，找到index$3对应的实际模块代码，把它的源文件路径放在引用它的文件前面。

2. 拆分打包Chunk #

Vite对超大单文件的模块排序更容易出问题，尝试拆分chunk，让依赖模块优先加载执行：

// vite.config.js
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // 把Redux相关模块单独拆包
          redux: ['redux', '@reduxjs/toolkit', './src/redux'],
          // 把React、ReactDOM等公共依赖拆包
          vendor: ['react', 'react-dom']
        }
      }
    }
  }
});

3. 排查并消除循环依赖 #

循环依赖是这类初始化顺序问题的高发诱因，用rollup-plugin-circular-dependency插件检测：

// vite.config.js
import circularDependency from 'rollup-plugin-circular-dependency';

export default defineConfig({
  build: {
    rollupOptions: {
      plugins: [
        circularDependency({
          exclude: /node_modules/,
          include: /src/,
          onDetected({ paths, module }) {
            console.warn('发现循环依赖:', paths);
          }
        })
      ]
    }
  }
});

找到循环依赖后，重构代码消除循环，或者调整模块的导入顺序。

4. 移除顶级异步逻辑 #

如果报错模块或其依赖存在顶级await，会延迟变量初始化，把异步逻辑移到函数内部：

// 错误写法：顶级await阻塞初始化
const config = await fetch('/api/config').then(res => res.json());

// 修正：把异步逻辑封装到初始化函数
let config;
async function initConfig() {
  config = await fetch('/api/config').then(res => res.json());
}
// 在应用启动时调用
initConfig();

5. 禁用预加载优化尝试 #

Vite默认生成的预加载链接可能干扰加载顺序，尝试禁用：

// vite.config.js
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        preload: false
      }
    }
  }
});

调试技巧 #

• 直接打开打包后的JS文件，搜索index$3，对比它的定义位置和报错行的引用位置，确认执行顺序问题。
• 在可疑模块的顶级作用域添加console.log('模块X执行')，观察浏览器控制台的打印顺序，定位先执行的问题模块。

内容的提问来源于stack exchange，提问作者CJ Thompson