Vue3 Vite 项目路径别名配置

问题描述

在 Vue3 + Vite 项目中，开发者希望通过使用 @ 别名来替代冗长的相对路径导入：

// 冗长的相对路径
import Component from '../../../../components/Component.vue'

// 期望使用别名
import Component from '@/components/Component.vue'

默认情况下，Vite 不会自动配置路径别名，需要手动设置。

解决方案

基础配置（推荐）

在 vite.config.js/ts 中配置路径别名：

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

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

TypeScript 支持

如果项目使用 TypeScript，还需要在 tsconfig.json 中添加路径映射：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Vite 官方推荐方式

Vite 官方推荐使用 import.meta.url 的方式：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})

多别名配置

可以为不同的目录设置多个别名：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: [
      { 
        find: '@', 
        replacement: fileURLToPath(new URL('./src', import.meta.url)) 
      },
      { 
        find: '@assets', 
        replacement: fileURLToPath(new URL('./src/assets', import.meta.url)) 
      },
      { 
        find: '@components', 
        replacement: fileURLToPath(new URL('./src/components', import.meta.url)) 
      }
    ]
  }
})

对应的 tsconfig.json：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@assets/*": ["./src/assets/*"],
      "@components/*": ["./src/components/*"]
    }
  }
}

常见问题与解决方案

1. TypeScript 无法识别别名

WARNING

即使 Vite 配置了别名，TypeScript 可能仍然显示 "Cannot find module" 错误。

确保 tsconfig.json 中正确配置了 paths，并且 Vite 和 TypeScript 的配置保持一致。

2. 动态路径问题

使用别名导入静态资源时，可能需要特殊处理：

// Util.ts
export const srcRoot = import.meta.url

export function img(name: string) {
  return new URL(`./assets/img/${name}.png`, srcRoot).toString()
}

// Vue 组件中使用
import { img } from '@/Util'

const imagePath = img('logo')

3. 路径解析错误

TIP

确保 vite.config.js 文件与 src 目录处于同一层级。如果不在同一层级，需要使用 ../ 前缀。

4. 包含嵌套文件

如果 TypeScript 无法检测到嵌套文件夹中的文件，可以修改 tsconfig.json：

{
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ]
}

完整示例

以下是一个完整的 Vue3 + Vite + TypeScript 项目配置示例：

vite.config.js

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
      '@components': fileURLToPath(new URL('./src/components', import.meta.url)),
      '@assets': fileURLToPath(new URL('./src/assets', import.meta.url))
    }
  }
})

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@assets/*": ["./src/assets/*"]
    }
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ]
}

App.vue

<script setup lang="ts">
import HelloWorld from '@/components/HelloWorld.vue'
import { img } from '@/utils/assets'

const logoPath = img('logo')
</script>

<template>
  <img :src="logoPath" alt="Logo">
  <HelloWorld msg="Hello Vue 3 + Vite" />
</template>

总结

配置 Vue3 + Vite 项目的路径别名需要两个步骤：

1. 在 vite.config.js 中配置 resolve.alias
2. 在 tsconfig.json 中配置 compilerOptions.paths（TypeScript 项目）

使用 Vite 官方推荐的 fileURLToPath(new URL('./src', import.meta.url)) 方式可以提高跨平台兼容性。确保两者配置一致，即可成功使用 @ 别名简化导入路径。