模块别名将import路径从相对路径转为基于项目根目录的固定标识，需在构建工具（Webpack/Vite）和TypeScript中分别配置alias与paths，确保一致并重启TS服务。
用模块别名（Aliases）替换一长串 ../../../../，核心就一条：让 import 路径从“相对位置计算”变成“基于项目根目录的固定标识”。这不光是写起来爽，更关键的是重构移动文件时不会满屏报错。
在构建工具里配置别名（以 Webpack 和 Vite 为例）
别名不是语言特性，而是构建工具提供的路径映射能力，必须显式配置。
-
Webpack：在
webpack.config.js的resolve.alias中添加：
resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
'@components': path.resolve(__dirname, 'src/components'),
'@utils': path.resolve(__dirname, 'src/utils')
}
}
-
Vite：在
vite.config.ts的resolve.alias中配置（支持字符串或对象）：
export default defineConfig({
resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
'@api': '/src/api',
'@assets': '/src/assets'
}
}
})
注意：/src 前加 / 是 Vite 的虚拟别名写法，等价于绝对路径映射；而 path.resolve 更通用，推荐统一使用。
TypeScript 需要同步声明别名类型
否则编辑器会标红、跳转失效、自动导入出错。在 tsconfig.json 的 compilerOptions 中补充：
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@components/*": ["src/components/*"],
"@utils/*": ["src/utils/*"]
}
}
}
⚠️ 关键细节：
- baseUrl 必须设为 "."（项目根目录），否则 paths 不生效；
- paths 的键值必须和构建工具中定义的别名**完全一致**（包括结尾 /*）；
- 修改后需重启 TypeScript 服务（VS Code 中按 Ctrl+Shift+P → “TypeScript: Restart TS server”）。
实际写法对比：从混乱到清晰
假设你在 src/pages/Dashboard/index.tsx 中要引入：
- 同级的
Header.tsx→ 还是./Header（无需别名）； - 位于
src/components/Chart/BarChart.tsx→ 改为import BarChart from '@components/Chart/BarChart'； - 位于
src/utils/request.ts→ 改为import { apiGet } from '@utils/request'； - 位于
src/assets/logo.svg→ 改为import logo from '@assets/logo.svg'。
不再需要数点数，也不怕把文件挪到子文件夹后路径全崩。
小技巧与避坑提醒
- 别名尽量语义化，比如
@api比@s更易懂、可维护； - 避免过度嵌套别名（如
@components/ui/button），优先用文件夹结构组织，别名只到一级逻辑层； - Eslint（如
import/resolver插件）也要同步配置别名，否则会警告“unable to resolve path”； - 如果用了 pnpm + workspace，确保别名指向的是实际源码路径，而非 node_modules 中的链接副本。
配置一次，所有 import 立刻变干净——这不是偷懒，是把注意力还给业务逻辑本身。
