Vite配置resolve.alias后@路径无法解析该如何正确处理？

resolve.alias 是Vite提供的路径别名配置项，作用是将复杂的相对路径映射为简短的别名前缀，避免开发时书写多层级的相对路径（如../../../../assets/xxx），同时统一路径引用规则，降低路径维护成本。

你遇到的404错误由两个问题共同导致：

1. 别名配置错误：path.resolve(__dirname, '/src')中/src是系统根路径写法，最终映射的是系统根目录下的src文件夹，而非当前项目根目录下的src文件夹，路径匹配失效。
2. Vite默认不会处理原生HTML文件内的别名路径：仅JS/TS、Vue/React单文件组件等模块内的路径引用会触发别名解析，直接写在HTML标签src属性里的别名不会被自动转换，浏览器会将@作为实际路径片段发起请求，因此返回404。

第一步：修正别名配置 #

将vite.config.js的配置修改为：

// vite.config.js
import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'), // 改为相对项目根目录的src文件夹
    },
  }
})

如果你的项目是ESModule模式（package.json中type: "module"），需要替换为适配ESM的路径写法：

// vite.config.js
import { defineConfig } from 'vite'
import path from 'path'
import { fileURLToPath } from 'url'

const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  }
})

第二步：处理HTML中的别名引用，可选方案任意选一个即可 #

• 方案1：动态赋值图片路径
  在对应的JS文件中引入图片资源，再动态赋值给img标签的src属性：

  // 页面对应的js文件
  import sampleImg from '@/assets/images/sample-1.jpg'
  document.querySelector('#target-img').src = sampleImg
  

  对应HTML修改为：

  <img id="target-img" alt="">
  

• 方案2：使用Vite插件支持HTML别名解析
  安装vite-plugin-html插件，配置后即可直接在HTML中使用别名：
  1. 安装依赖：npm i vite-plugin-html -D
  2. 修改vite.config.js配置，引入插件：

  import { createHtmlPlugin } from 'vite-plugin-html'
  export default defineConfig({
    // ... 原有配置
    plugins: [
      createHtmlPlugin({
        minify: true,
      }),
    ]
  })
  

  配置后原来的<img src="@/assets/images/sample-1.jpg">即可正常生效。
• 方案3：如果图片无需构建处理，可将图片放入项目根目录的public文件夹下，直接使用根路径引用：
  把sample-1.jpg放入public/assets/images/目录，HTML直接写：

  <img src="/assets/images/sample-1.jpg">
  

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