Vite打包后的基础路径如何配置？

Question

在使用 Vite 进行项目打包时，如何正确配置打包后的基础路径（base path）是一个常见问题。特别是在将项目部署到非根路径（如：/my-app/）或 CDN 地址下时，若 base 配置不当，会导致静态资源加载失败。Vite 默认使用相对路径（base: './'），适用于大多数子路径部署场景，但在某些服务器结构或 CDN 场景中，需显式设置绝对路径（如 base: '/my-app/' 或 base: 'https://cdn.example.com/'）。此外，base 还会影响路由、公共资源引用及插件行为。因此，理解不同部署环境下 base 的配置方式是确保项目正常运行的关键。

Answer 1

一、理解 Vite 中 base 配置的作用

Vite 的 base 配置项用于指定项目打包后资源的基础路径。它直接影响 HTML 文件中引用的静态资源（如 JS、CSS、图片等）的 URL 前缀。

• 默认值为 './'，表示相对路径。
• 部署到子路径时，应设置为类似 '/my-app/' 的绝对路径。
• 使用 CDN 分发时，可设置为完整的外部 URL，如 'https://cdn.example.com/assets/'。

二、不同部署环境下的 base 配置方式

根据部署目标的不同，base 的配置策略也有所区别：

部署场景	推荐 base 值	说明
本地开发或测试服务器	'./'	使用相对路径最为灵活。
部署到子路径（如 /my-app/）	'/my-app/'	确保服务器配置支持该路径下文件的访问。
使用 CDN 托管资源	'https://cdn.example.com/'	需配合构建输出目录与 CDN 路径一致。

三、base 配置对其他模块的影响

base 不仅影响静态资源路径，还会影响以下方面：

1. 前端路由：若使用 Vue Router 或 React Router 等客户端路由，其 base 需与 Vite 配置保持一致。
2. 公共资源引用：在代码中通过 import 引入的资源会自动加上 base 前缀。
3. 插件行为：部分插件（如 unplugin-vue-components）可能依赖 base 来正确解析路径。

四、配置示例及注意事项

以下是一个典型的 vite.config.js 中的 base 配置示例：

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

export default defineConfig({
  plugins: [vue()],
  base: '/my-app/'
})
  

注意事项：

• 确保服务器配置能正确映射 base 路径下的资源请求。
• CDN 场景下，建议使用版本号命名资源以避免缓存问题。
• 动态修改 base 可通过命令行参数或环境变量实现。

五、典型问题排查流程图

当遇到资源加载失败时，可通过如下流程判断是否是 base 配置问题：

graph TD
      A[页面加载失败] --> B{检查浏览器控制台是否有 404 错误？}
      B -- 是 --> C[确认 base 配置是否匹配部署路径]
      C --> D[查看 HTML 中资源路径是否正确]
      D --> E[检查服务器或 CDN 是否正确映射路径]
      B -- 否 --> F[可能是其他网络或代码错误]