从Vite 4迁移至Vite 5遇SVG导入路径问题求助

问题概述 #

• 从 Vite 4.4.5 升级到 Vite 5.0.10 后，src/components/Header/Header.tsx 中执行 import sprite from 'assets/sprite.svg';，本地开发时资源路径正常，但部署到 GitHub Pages 后出现路径错误，Vite 4 版本无此问题。

解决方案 #

1. 修正 Vite 配置中的 base 参数 #

GitHub Pages 部署项目站点（非自定义域名根站点）时，必须将 base 设置为仓库名称。在 vite.config.ts 中添加或调整配置：

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

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      'assets': path.resolve(__dirname, './src/assets') // 确认别名指向正确的资源目录
    }
  },
  // 生产环境下设置为仓库名称，开发环境保持根路径
  base: process.env.NODE_ENV === 'production' ? '/react_vite_ts/' : '/'
});

2. 确认 SVG 资源的使用方式 #

导入 SVG 后直接使用返回的 URL 即可，Vite 5 会自动在生产环境中拼接正确的 base 路径：

import sprite from 'assets/sprite.svg';

// 正确使用示例
<svg className="icon">
  <use href={`${sprite}#目标图标ID`} />
</svg>

3. 清理缓存并重新构建 #

执行以下命令清理旧缓存，避免残留的构建文件导致路径异常：

rm -rf dist node_modules
npm install
npm run build

4. 检查 GitHub Pages 部署配置 #

确保 GitHub Pages 部署的是 dist 目录下的构建产物：

• 在仓库的「Settings」→「Pages」中，确认部署源选择的是正确的分支（如 gh-pages）或直接指定 dist 目录（若使用 GitHub Actions 部署）。

问题原因 #

Vite 5 对静态资源的 URL 生成逻辑做了调整，生产环境下资源路径严格依赖 base 配置。Vite 4 可能存在自动适配的兼容逻辑，而 Vite 5 更强调显式配置，未设置正确的 base 会导致部署后资源从域名根目录查找，而非仓库子目录，最终引发路径错误。

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