前端工程化 / 系统课时
配置路径别名
配置路径别名
本课解决深层相对路径难读、移动文件后易失效的问题。你将同时配置 Vite 的运行时解析和 TypeScript 的编辑器解析,让 @/utils/format 在开发、类型检查与生产构建中指向同一个文件。
学习目标
- 使用
resolve.alias把稳定前缀映射到项目目录 - 在 TypeScript 配置中声明相同的
paths - 通过类型检查和生产构建验证两套解析结果一致
先认识两套路径解析
编辑器中的跳转、补全和类型检查由 TypeScript 解析器负责;开发服务器与生产构建由 Vite 解析器负责。只改一侧时,常见现象是“编辑器报红但页面能运行”,或“编辑器正常但构建提示找不到模块”。

Vite 的文件系统别名应使用绝对路径;相对替换值不会自动转换为文件系统绝对路径。:contentReference[oaicite:0]{index=0}
配置同一个别名
在现有 Vite + TypeScript 项目的 vite.config.ts 中配置运行时别名。fileURLToPath 可以在 ESM 配置文件中稳定地把相对 URL 转成绝对路径。
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
export default defineConfig({
resolve: {
alias: {
// 运行时和构建阶段:@ 始终指向项目根目录下的 src
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
})再把同一规则写入负责应用源码的 TypeScript 配置。Vite 官方模板常使用 tsconfig.app.json;若项目只有一个 tsconfig.json,就在该文件中配置。
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
},
"include": ["src"]
}@ 与 @/* 的写法职责不同:Vite 将导入前缀替换为绝对目录,TypeScript 则用通配符把 @/x 映射到 src/x。两边最终目录必须一致。
编写导入并执行验证
创建一个最小模块和入口引用。示例假设项目已有 src/main.ts,可以替换其中内容。
// src/utils/format.ts
export function formatUser(name: string): string {
return `User: ${name.trim()}`
}
// src/main.ts
import { formatUser } from '@/utils/format'
console.log(formatUser(' Ada '))先让 TypeScript 检查编辑器侧配置,再让 Vite 执行生产构建。命令中的版本、模块数、文件大小和耗时会因项目而不同。
npx tsc --noEmit && npm run build预期输出
vite v<VERSION> building client environment for production...
✓ <COUNT> modules transformed.
dist/index.html <SIZE>
dist/assets/index-<ID>.js <SIZE>
✓ built in <TIME>tsc --noEmit 成功时通常没有输出;随后出现构建完成信息,说明 TypeScript 与 Vite 都能解析该别名。
处理典型不一致
编辑器仍报错时,先确认修改的是实际参与应用编译的 tsconfig,而不是只负责项目引用的根配置;随后重启编辑器的 TypeScript 服务。构建失败时,检查 replacement 是否为绝对路径、目录大小写是否与磁盘一致,以及导入是否错误写成 @utils/...。
不要让 Vite 指向 src、TypeScript 却指向 src/app。这类配置可能在部分文件中暂时可用,但重构、测试或 CI 构建时会暴露不一致。