使用Vite构建React静态文件后页面空白的问题排查

核心问题拆解 #

• Vite 不支持 Create React App 中的homepage字段，你添加的这个配置完全无效，直接删除即可。
• 静态部署场景下，BrowserRouter依赖服务器配置将所有路由请求 fallback 到index.html，如果服务器未做对应配置，不仅子路由访问会失败，甚至首页也可能因路由匹配逻辑出现空白。

具体修复步骤 #

1. 清理无效配置
   删除package.json中的"homepage": "/"字段，Vite通过vite.config.js里的base属性控制公共资源路径。

2. 调整路由配置（二选一）

   • 方案一：改用HashRouter（无需服务器配置，适配静态托管场景）
     修改App.js中的路由组件：

     // 替换BrowserRouter为HashRouter
     import {HashRouter,Routes,Route} from 'react-router-dom'
     
     function App() {
       return (
         <>
             <HashRouter>
               <Routes>
                 <Route path='/' element={<Home/>} />
                 <Route path='/influencer' element={<BecomeInfluncer/>} />
                 <Route path='/term-condition' element={<TermCondition />} />
                 <Route path='/privacy-policy' element={<PrivacyPolicy/>} />
                 <Route path='*' element={<ErrorPage />} />
               </Routes>
             </HashRouter>
         </>
       )
     }
     

   • 方案二：保留BrowserRouter，配置服务器fallback规则
     若必须使用BrowserRouter，需让服务器将所有请求转发到index.html：
     • Nginx：在站点配置中添加try_files $uri $uri/ /index.html;
     • Apache：创建.htaccess文件并写入：

       RewriteEngine On
       RewriteBase /
       RewriteRule ^index\.html$ - [L]
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteCond %{REQUEST_FILENAME} !-d
       RewriteRule . /index.html [L]
       

3. 验证构建结果
   执行npm run build完成构建后，用vite preview本地预览产物，打开浏览器控制台查看是否存在资源加载失败或JS报错——多数空白页问题都是由这类隐性错误导致的。

4. 确认base配置合理性
   如果项目部署在子目录（如https://xxx.com/my-project/），将vite.config.js中的base改为"/my-project/"；若部署在根目录，设为"/"即可，当前的"./"相对路径也能正常工作，但根目录场景下"/"更稳妥。

内容的提问来源于stack exchange，提问作者Muhammad Rehan