React+Vite项目部署至Cpanel后显示空白页，如何解决？

常见原因及对应解决方法 #

1. Vite的base路径配置错误 #

• 原因：开发模式默认根路径是/，但部署到Cpanel时若项目不在域名根目录（比如放在子目录/my-react-app下），Vite打包的资源路径会出错，导致JS/CSS加载失败，React无法完成挂载，body自然没有内容。
• 解决：在项目根目录的vite.config.js（或vite.config.ts）中设置正确的base路径：

  export default defineConfig({
    // 部署在域名根目录就设为'/'；在子目录（比如public_html/my-app）就设为'/my-app/'
    base: '/your-subdirectory-path/', 
    // 其他原有配置...
  })
  

  修改后重新执行npm run build，再把新生成的dist文件夹内的所有文件上传到Cpanel对应目录。

2. Cpanel部署路径不正确 #

• 原因：如果域名指向Cpanel的public_html目录，但你把dist文件夹整个上传，或者把dist内的文件放到了错误的子目录，都会导致服务器找不到正确的index.html资源。
• 解决：
  • 部署在域名根目录：直接把dist文件夹里的所有文件（包括index.html、assets文件夹等）上传到Cpanel的public_html目录，不要上传整个dist文件夹。
  • 部署在子目录：比如要通过yourdomain.com/my-app访问，就在public_html下新建my-app文件夹，把dist内的所有文件上传到这个my-app文件夹，同时确保vite.config里的base设置为/my-app/。

3. 资源加载权限或路径问题 #

• 原因：Cpanel上的文件权限设置错误，浏览器无法加载JS/CSS资源；或者打包后的资源路径在index.html中不匹配部署路径，导致资源加载失败。
• 解决：
  • 调整文件权限：在Cpanel文件管理器中，右键点击assets文件夹，把权限设为755；文件夹里的文件权限设为644。
  • 检查index.html资源路径：打开dist里的index.html，查看script和link标签的src/href是否和部署路径匹配，比如base设为/my-app/的话，资源路径应该是/my-app/assets/index.xxx.js。

4. 浏览器缓存问题 #

• 原因：浏览器缓存了旧的index.html或资源文件，加载的是失效内容，导致页面空白。
• 解决：
  • 按Ctrl+Shift+R（Windows）或Cmd+Shift+R（Mac）强制刷新页面，清除浏览器缓存。
  • 若Cpanel开启了服务器端缓存，进入对应缓存管理面板清空缓存。

5. React Router路由模式问题（使用了React Router时） #

• 原因：如果用了BrowserRouter，Cpanel服务器没有配置 fallback到index.html，初始加载或刷新页面时会出现资源找不到的情况，导致React无法渲染内容。
• 解决：
  • 若使用Apache服务器，在部署目录下新建.htaccess文件，添加以下内容：

    <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteBase /your-subdirectory-path/ # 根目录写/即可
      RewriteRule ^index\.html$ - [L]
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteRule . /your-subdirectory-path/index.html [L] # 根目录写/index.html
    </IfModule>
    

  • 若使用Nginx服务器，需配置对应location规则，确保所有请求都指向index.html。

内容的提问来源于stack exchange，提问作者Samiul Islam