Vite打包路径配置后静态资源404

Question

在使用 Vite 构建 Vue 或 React 项目时，若将 `base` 配置项修改为相对路径（如 `'./'`）或自定义路径（如 `'/assets/'`），常出现静态资源加载 404 的问题。典型表现为：页面可访问，但 CSS、JS 或图片等资源请求返回 404。此问题多因 `vite.config.js` 中 `base` 路径设置不当，或构建后资源路径未正确解析所致。尤其在部署到非根目录（如 GitHub Pages 子路径）时，若未同步调整 `base` 与服务器路由配置，极易引发资源定位失败。需确保 `base` 与部署环境匹配，并验证输出的资源引用路径是否正确。

Answer 1

深入解析 Vite 中 base 配置导致的静态资源 404 问题

1. 问题背景与典型表现

在使用 Vite 构建 Vue 或 React 项目时，base 配置项用于指定应用的公共基础路径。当部署到非根目录（如 GitHub Pages 的子路径 /my-app/）时，若未正确设置 vite.config.js 中的 base 值，常导致构建后资源请求返回 404 错误。

典型表现为：

• HTML 页面可正常加载；
• CSS、JavaScript、图片等静态资源请求失败；
• 浏览器控制台报错：如 GET /assets/index.xxx.js 404；
• 资源路径未按预期拼接 base 路径。

2. 核心机制：Vite 的 base 配置原理

base 是 Vite 构建阶段用于生成资源引用路径前缀的关键配置。其值影响以下内容：

配置项	默认值	作用
base	'/'	所有静态资源的公共前缀路径
build.outDir	'dist'	输出目录
build.assetsDir	'assets'	资源文件子目录

3. 常见错误配置示例

/**
 * vite.config.js 错误配置案例
 */
export default defineConfig({
  base: '/wrong-path/', // 部署路径实际为 /my-app/
  build: {
    outDir: 'dist'
  }
})

上述配置会导致资源请求指向 /wrong-path/assets/...，而服务器并未在此路径下提供资源，从而引发 404。

4. 正确配置策略

根据部署环境选择合适的 base 值：

• 部署至域名根路径（如 https://example.com/）：设置 base: '/'；
• 部署至子路径（如 https://user.github.io/my-app/）：设置 base: '/my-app/'；
• 本地相对路径运行（无需服务器）：设置 base: './'。

5. 动态 base 配置实践

为适配多环境部署，推荐通过环境变量动态设置 base：

// vite.config.js
import { defineConfig } = require('vite')

module.exports = defineConfig(({ mode }) => {
  return {
    base: process.env.VITE_BASE_PATH || '/',
    build: {
      outDir: 'dist'
    }
  }
})

6. 构建产物路径验证方法

构建完成后，检查 dist/index.html 中资源引用是否包含正确的 base 前缀：

<link rel="stylesheet" href="/my-app/assets/index.css">
<script type="module" src="/my-app/assets/index.js"></script>

若缺少 /my-app/ 前缀，则说明 base 未生效或被覆盖。

7. 服务器路由配置同步要求

尤其在使用 GitHub Pages、Nginx 或 Apache 部署时，需确保服务器能正确服务静态资源。例如 Nginx 配置：

location /my-app/ {
    alias /var/www/html/my-app/;
    try_files $uri $uri/ /my-app/index.html;
}

该配置保证 SPA 路由回退至入口 HTML，并正确解析带 base 前缀的资源请求。

8. 相对路径陷阱分析

设置 base: './' 可避免绝对路径依赖，但存在局限性：

• 无法支持深层路由（如 /page/a）下的资源定位；
• 部分 CDN 或代理服务器不兼容相对路径资源引用；
• 开发服务器与生产环境行为不一致，增加调试难度。

9. CI/CD 中的自动化处理方案

结合 CI 环境变量自动注入 base 路径：

# .github/workflows/deploy.yml
- name: Build with base path
  run: |
    VITE_BASE_PATH=/${{GITHUB_REPOSITORY##*/}/ npm run build

10. Mermaid 流程图：base 配置决策逻辑

graph TD
            A[开始] --> B{部署环境?}
            B -->|根域名| C[base = '/']
            B -->|子路径| D[base = '/subpath/']
            B -->|本地预览| E[base = './']
            C --> F[构建项目]
            D --> F
            E --> F
            F --> G[检查 index.html 资源路径]
            G --> H{路径正确?}
            H -->|是| I[部署成功]
            H -->|否| J[调整 base 配置]
            J --> F

11. 高级技巧：运行时动态 base 探测

对于无法预知部署路径的场景，可通过 JS 在运行时探测 base：

// main.js 或 entry point
const currentPath = new URL(import.meta.url).pathname
const basePath = currentPath.substring(0, currentPath.lastIndexOf('/') + 1)
// 用于动态加载模块或设置 API 基础地址

12. 跨框架兼容性对比

构建工具	等效配置项	注意事项
Vite	base	影响所有资源和路由前缀
Webpack (Vue CLI)	publicPath	语义相同，行为一致
Create React App	homepage in package.json	需配合 %PUBLIC_URL% 使用