Vite中配置路径别名需两步：一是在vite.config.ts的resolve.alias中用path.resolve设置精确路径映射，如'@': resolve(__dirname, 'src')；二是同步在tsconfig.json中配置baseUrl和paths，如"@/": ["src/"]，缺一则导致模块解析失败或类型提示失效。
在 Vite 中配置路径别名，核心是两步：修改 vite.config.ts 的 resolve.alias，并同步配置 tsconfig.json（或 jsconfig.json）让 TypeScript/IDE 正确识别。缺一不可，否则会出现「模块解析失败」或「类型提示不生效」。
1. 在 vite.config.ts 中设置 alias
打开项目根目录的 vite.config.ts（或 vite.config.js），在 resolve.alias 中添加映射规则。推荐使用 path.resolve 确保路径准确：
- ✅ 推荐写法（TypeScript）：
import { defineConfig } from 'vite';<br>import { resolve } from 'path';<br><br>export default defineConfig({<br> resolve: {<br> alias: {<br> '@': resolve(__dirname, 'src'),<br> '@components': resolve(__dirname, 'src/components'),<br> '@utils': resolve(__dirname, 'src/utils')<br> }<br> }<br>});
-
⚠️ 注意：别名末尾不加斜杠（如
'@/'），Vite 默认不强制要求结尾斜杠，但加了反而可能在某些插件中引发歧义； -
? 提示：多个别名建议按语义分组，避免全用
@套娃（例如@/api和@/api/index.ts冲突时难调试）。
2. 配置 tsconfig.json 支持路径映射
仅 Vite 配置 alias 不够——TypeScript 编译器和 VS Code 不会自动识别，需在 tsconfig.json 的 compilerOptions.baseUrl 和 paths 中声明：
立即学习“Java免费学习笔记（深入）”；
{<br> "compilerOptions": {<br> "baseUrl": "./",<br> "paths": {<br> "@/*": ["src/*"],<br> "@components/*": ["src/components/*"],<br> "@utils/*": ["src/utils/*"]<br> }<br> }<br>}
-
✅ 关键点：
baseUrl设为"./"是前提，否则paths不生效； -
✅ 路径通配符必须一致：
alias里写'@'，paths就得写"@/*"，且右侧目标路径要以/*结尾； -
? 小技巧：改完
tsconfig.json后，重启 VS Code 或运行npm run tsc --noEmit验证是否报错。
3. 实际使用示例
配置完成后，即可在代码中直接引入：
// 普通组件引入<br>import Header from '@components/Header.vue';<br><br>// 工具函数<br>import { formatDate } from '@utils/date';<br><br>// 全局类型定义（配合 declare module）<br>import type { User } from '@types/user';
-
✅ 支持自动补全与跳转：VS Code 点击
@components/Header.vue可直接跳转到文件； -
⚠️ 注意：别名只作用于模块导入（
import/require），不适用于 CSS 中的url()或 HTML 的src属性（这些需用相对路径或 public 目录）。
4. 常见问题排查
如果别名不生效，按顺序检查以下几项：
- Vite 服务是否已重启？修改
vite.config.ts后必须重启开发服务器； -
tsconfig.json是否在项目根目录？子目录下的tsconfig.json可能被忽略； - 是否混淆了
resolve.alias的 key 类型？字符串 key 如'@'是精确匹配，不支持正则； - 是否在
.d.ts文件中用了别名但没配paths？TS 类型文件同样依赖tsconfig.json的paths。
