React+Vite项目部署Vercel失败：仅index.html生效，资源路径异常

1. assets 目录存放资源是正常的 #

Vite 默认打包后会将 JS、CSS 等静态资源归类到 dist/assets 目录下，这是框架标准的打包结构，完全符合规范，不是导致页面空白的原因。

2. 页面空白、资源加载失败的原因及解决办法 #

原因1：基础路径(base)配置错误 #

Vite 默认 base 配置为 /，但如果你的项目部署在 Vercel 子路径下（如 https://xxx.vercel.app/your-project），或部署路径并非根域名，会导致资源引用路径不匹配，进而加载失败。

解决办法： #

修改 vite.config.js/vite.config.ts 中的 base 配置：

• 若部署在根域名（如 https://your-project.vercel.app），设置为 base: './'（相对路径更适配部署场景）；
• 若部署在子路径，设置为 base: '/your-project-name/'（注意首尾斜杠）。
  示例代码：

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

export default defineConfig({
  plugins: [react()],
  base: './'
})

原因2：Vercel 部署配置未正确指向 dist 目录 #

Vercel 虽能自动识别 Vite 项目，但偶尔会出现配置偏差，需手动确认：

• 进入 Vercel 项目后台，打开「Settings」->「Build & Development Settings」；
• 检查「Output Directory」是否设置为 dist；
• 若配置错误，修正后重新触发部署。

原因3：资源引用路径大小写不匹配 #

Vercel 服务器对路径大小写敏感，若代码中资源引用的大小写与实际文件路径不一致（如代码写 Assets/main.js，实际是 assets/main.js），会导致加载失败。需逐一检查代码中的资源引用，确保大小写完全匹配。

3. 验证方法 #

修改配置后重新执行 npm run build，查看 dist/index.html 中的资源引用路径：

• 若设置 base: './'，资源路径应类似 ./assets/main.xxx.js，这种相对路径能保证部署后正确加载。

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