Vue3 - Vite项目中src别名@配置问题解决

技术背景

在Vue3 - Vite项目开发中，当导入组件时，可能会遇到路径过长的问题，如import Component from '../../../../components/Component.vue'。为了简化路径，我们通常会使用别名来替代src目录，例如使用@作为src的别名，这样就可以写成import Component from '@/components/Component.vue'。然而，在实际配置过程中，可能会出现别名配置不生效的情况。

实现步骤

步骤1：配置vite.config.js或vite.config.ts文件

在Vite项目中，需要在配置文件中设置别名。以下是几种常见的配置方式：

方式一：使用path模块

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'),
    },
  }
})

方式二：使用fileURLToPath和URL

import { fileURLToPath, URL } from "url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

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

步骤2：配置tsconfig.json或jsconfig.json文件（可选）

如果项目使用TypeScript，为了让编辑器能够正确识别别名，需要在tsconfig.json中配置paths：

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

如果项目使用JavaScript，可在jsconfig.json中进行类似配置：

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

核心代码

以下是完整的vite.config.ts和tsconfig.json配置示例：

vite.config.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'),
    },
  }
})

tsconfig.json

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

最佳实践

• 多别名配置：除了配置@别名，还可以配置其他别名，如@assets、@cmp等，方便快速定位不同类型的文件。

import { fileURLToPath, URL } from "url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

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

• 保持配置文件同步：确保vite.config.js和tsconfig.json中的别名配置一致，避免出现路径解析错误。

常见问题

1. 启动开发服务器时出现警告

Unrestricted file system access to "C:/Projects/my-vite-project/src/main.ts" For security concerns, accessing files outside of serving allow list will be restricted by default in the future version of Vite. Refer to vitejs.dev/config/#server-fs-allow for more details.

解决方法：根据警告提示，参考vitejs.dev/config/#server-fs-allow进行相应配置。

2. 编辑器提示找不到模块

解决方法：检查tsconfig.json或jsconfig.json中的paths配置是否正确，确保与vite.config.js中的别名配置一致。

3. 动态属性中别名不生效

解决方法：可以通过定义路径解析函数来解决，例如：

// Util.ts
export const srcRoot = import.meta.url;
export function img(name: string) {
  return new URL(`./assets/img/${name}.png`, srcRoot)
}

// App.vue
<script>
import {img} from "./Util";
</script>

<template>
<img  :src="img('logo')" />
</template>