Vite + React开发模式打包异常：页面空白且无限加载

可能成因 #

• 依赖预构建未完成：Vite启动时会自动预构建第三方依赖转为ESM格式，若依赖数量多、网络差或预构建被中断，浏览器会直接请求大量未处理的模块，导致加载阻塞。
• 入口配置错误：HTML文件位置不对、script标签未设type="module"，或vite.config.js中入口路径配置错误，导致应用无法正确初始化。
• 遗留CRA代码/配置：代码中残留Webpack专属语法（如require.context、不当使用__dirname），或环境变量仍用CRA的process.env格式，Vite无法解析。
• 路由兼容性问题：React Router的懒加载写法不符合Vite规范，或路由匹配规则错误，导致初始页面无组件渲染。
• 版本/插件冲突：Vite与@vitejs/plugin-react版本不兼容，或第三方插件干扰了模块打包流程。

修复方案 #

1. 解决依赖预构建问题 #

• 启动Vite后等待终端预构建日志完成（出现ready in X ms提示）再访问页面，不要提前打开浏览器。
• 手动预构建依赖：执行npx vite optimize，完成后再启动npm run vite。
• 优化预构建范围：在vite.config.js中配置optimizeDeps，排除已为ESM格式的依赖，减少预构建时间：

  export default defineConfig({
    optimizeDeps: {
      exclude: ['esm-dependent-package']
    }
  })
  

2. 校验入口配置 #

• 确保index.html放在项目根目录，内部script标签正确指向入口文件：

  <script type="module" src="/src/index.jsx"></script>
  

• 检查vite.config.js的入口配置，若自定义了build.rollupOptions.input，需指向正确的HTML路径：

  export default defineConfig({
    build: {
      rollupOptions: {
        input: './index.html'
      }
    }
  })
  

3. 清理CRA遗留内容 #

• 替换Webpack专属语法：将require.context改为Vite的import.meta.glob；Node环境下的__dirname用import.meta.url转换：

  // 替换前
  const modules = require.context('./components', false, /\.jsx$/);
  // 替换后
  const modules = import.meta.glob('./components/*.jsx');
  

• 替换环境变量：将process.env.REACT_APP_XXX改为import.meta.env.REACT_APP_XXX，若需兼容旧代码，可在vite.config.js中添加：

  export default defineConfig({
    define: {
      'process.env.REACT_APP_XXX': JSON.stringify(import.meta.env.REACT_APP_XXX)
    }
  })
  

• 移除react-scripts等CRA依赖，确保package.json中只有Vite相关依赖（如vite、@vitejs/plugin-react）。

4. 调整路由配置 #

• 确保React Router懒加载配合Suspense使用，且动态导入路径为相对路径：

  import { Suspense, lazy } from 'react';
  const Home = lazy(() => import('./pages/Home'));
  
  function App() {
    return (
      <Suspense fallback={<div>Loading...</div>}>
        <Routes>
          <Route path="/" element={<Home />} />
        </Routes>
      </Suspense>
    );
  }
  

• 检查初始路由是否正确匹配，避免出现无组件渲染的情况。

5. 排查版本与插件 #

• 确认Vite与@vitejs/plugin-react版本兼容：Vite 4.x对应plugin-react 4.x，Vite 5.x需plugin-react 4.2.0+，执行npm install vite@latest @vitejs/plugin-react@latest升级到匹配版本。
• 暂时禁用所有第三方Vite插件（如压缩、代码分析类），逐步启用排查是否有插件导致问题。

内容的提问来源于stack exchange，提问作者Alex Ryshkov