vite中base配置路径错误导致资源404

Question

在使用 Vite 构建项目时，若未正确配置 `base` 路径，部署到非根目录（如 GitHub Pages 的子路径）时常导致静态资源 404 错误。例如，`base` 仍为默认 `'/'`，但实际部署路径为 `/project/`，浏览器将无法加载 `/assets/*` 资源。正确做法是在 `vite.config.js` 中设置 `base: '/project/'`，确保资源路径相对或绝对正确，避免请求路径错位引发的 404 问题。

Answer 1

1. 问题背景与现象描述

在使用 Vite 构建前端项目时，开发者常忽略 base 配置项的重要性。当项目部署至非根路径（如 GitHub Pages 的子目录 /project/）时，若未正确设置 base，构建后的静态资源请求路径仍以 / 为前缀，导致浏览器请求 /assets/main.js 而非 /project/assets/main.js，从而引发大量 404 错误。

• 典型报错：Failed to load resource: the server responded with a status of 404 (Not Found)
• 影响范围：CSS、JS、图片等所有通过相对根路径引用的静态资源
• 常见场景：GitHub Pages、GitLab Pages、Nginx 子目录部署、CDN 子路径映射等

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

base 是 Vite 构建配置中的关键字段，定义了应用的公共基础路径。它直接影响：

1. HTML 文件中资源引用的生成（如 <script src="/assets/app.js">）
2. 动态导入模块的路径前缀
3. 静态资源哈希 URL 的拼接逻辑
4. 开发服务器代理和热更新路径的基础

配置值	适用场景	构建输出示例
'/'	部署在域名根路径（如 example.com）	<script src="/assets/app.js">
'/project/'	GitHub Pages 子路径（example.com/project/）	<script src="/project/assets/app.js">
'./'	本地文件系统运行或未知部署路径	<script src="./assets/app.js">

3. 实际配置方法与代码示例

在 vite.config.js 中正确设置 base 是解决该问题的核心步骤：

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

export default defineConfig({
  base: '/project/', // 关键配置：指定部署子路径
  plugins: [vue()],
  build: {
    outDir: 'dist',
    assetsDir: 'assets'
  }
})

此外，可结合环境变量实现多环境灵活配置：

export default defineConfig(({ mode }) => ({
  base: mode === 'production' ? '/project/' : '/',
  plugins: [...]
}))

4. 自动化检测与流程图辅助分析

为避免人为疏忽，可通过 CI/CD 流程自动校验 base 配置是否匹配目标部署路径。以下为部署前的路径校验流程：

graph TD A[开始部署] --> B{是否为子路径部署?} B -- 是 --> C[读取预期 base 值 /project/] B -- 否 --> D[使用 base '/' 或 './'] C --> E[解析 vite.config.js 中的 base] E --> F{配置值 == 预期?} F -- 否 --> G[抛出错误并终止] F -- 是 --> H[继续构建与部署]

5. 进阶问题与扩展思考

除了基本的 base 设置，还需关注以下关联问题：

• 路由模式冲突：若使用 Vue Router 的 history 模式，需确保服务器对 /project/* 所有路径回退到 index.html
• CDN 分发策略：当资源托管于 CDN 时，base 可设为完整 URL（如 https://cdn.example.com/project/）
• 微前端集成：在 qiankun 等框架中，base 需与主应用注册路径一致，避免沙箱外资源加载失败
• 动态 publicPath：某些场景下需运行时动态调整资源路径，可通过重写 window.publicPath 实现（适用于 Webpack 兼容层）