如何通过cPanel将React+Vite项目（dist文件夹）部署到私有虚拟主机？

以下是针对你遇到的问题的分步解决方案：

1. 确认Vite的基础路径配置 #

Vite打包后的资源路径依赖vite.config.js里的base配置，部署到虚拟主机根目录（public_html）时，必须确保路径正确：

• 打开项目根目录的vite.config.js，添加或修改base配置为根路径：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/' // 对应public_html的根目录，必须设置为'/'
})

• 执行npm run build重新生成dist文件夹，再上传里面的所有内容到public_html。

2. 正确上传打包文件 #

确保你上传的是dist文件夹内部的所有文件和子文件夹，而不是dist文件夹本身：

• 比如dist里的index.html、assets文件夹要直接放在public_html根目录下，不能出现public_html/dist/xxx的嵌套结构。

3. 修复SPA路由问题（如果使用了React Router） #

如果你的任务清单用了客户端路由（比如BrowserRouter），cPanel默认无法处理SPA的路由跳转，刷新或直接访问子路由会导致404，进而引发白屏：

• 在public_html目录下创建.htaccess文件，添加以下重写规则：

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

这个规则会将所有非文件/非目录的请求转发到index.html，让React Router接管路由处理。

4. 检查文件权限 #

cPanel的文件权限不正确会导致服务器无法读取资源：

• 在cPanel文件管理器中选中所有上传的文件和文件夹，右键选择「更改权限」；
• 设置文件权限为644，文件夹权限为755，保存后刷新页面。

5. 强制清除浏览器缓存 #

浏览器缓存的旧资源可能导致白屏：

• 按Ctrl+Shift+R（Windows/Linux）或Cmd+Shift+R（Mac）强制刷新页面，或者手动清空浏览器缓存后重新访问。

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