Vue 3 项目配置 Vite 路径别名需两步:一是在 vite.config.ts 中通过 resolve.alias 设置运行时路径映射,如 '@': resolve(__dirname, 'src');二是在 tsconfig.json 的 compilerOptions 中配置 baseUrl 和 paths,如 "@/": ["src/"],缺一不可,否则编辑器报错、类型提示失效或构建失败。

Vue 3 项目初始化时设置 Vite 路径别名,核心是两步:在 vite.config.ts(或 .js)里配置 resolve.alias,再在 tsconfig.json 中同步声明 TypeScript 的路径映射。缺一不可,否则编辑器会报错、类型提示失效,甚至构建可能出问题。
修改 vite.config.ts 配置别名
这是运行时生效的关键。Vite 通过 resolve.alias 告诉打包器和开发服务器如何解析带 @ 的导入路径。
- 确保已安装
@types/node(TypeScript 项目必需):npm install -D @types/node - 在
vite.config.ts的resolve选项中添加 alias:
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
'@': resolve(__dirname, 'src')
}
}
})
这样 import xxx from '@/components/Hello.vue' 就等价于从 src/components/Hello.vue 加载。
同步更新 tsconfig.json 声明路径
TypeScript 编译器不读 vite.config.ts,必须单独告诉它 @/* 对应什么位置,否则 VS Code 或 WebStorm 会标红、跳转失败、无自动补全。
- 打开
tsconfig.json,在compilerOptions下添加baseUrl和paths:
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
注意:"baseUrl": "." 是必要前提,paths 才能基于它做相对解析。改完保存,重启 IDE 或执行 Reload Window。
可选:增加更多实用别名
除了 @,你还可以按需扩展,提升组织清晰度:
-
'@assets': resolve(__dirname, 'src/assets')→ 专用于图片、字体等静态资源 -
'@api': resolve(__dirname, 'src/api')→ 统一管理请求模块 -
'@utils': resolve(__dirname, 'src/utils')→ 工具函数集中引用
对应地,在 tsconfig.json 的 paths 中也加上一行,例如:"@assets/*": ["src/assets/*"]。
验证是否生效
写一个简单测试即可确认:
- 在任意
.vue或.ts文件中尝试:import { useUserStore } from '@/stores/user' - 保存后看编辑器是否能正常跳转、无报错;
- 终端运行
npm run dev,确保页面加载不报Module not found错误。
如果跳转失败但运行正常,大概率是 tsconfig.json 没配或没重载;如果直接报错找不到模块,则 vite.config.ts 的 alias 路径写错了,检查 resolve(__dirname, 'src') 是否拼写正确、src 目录是否存在。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











