模块别名是解决大型前端工程路径混乱问题最直接有效的方式，它将冗长脆弱的相对路径如../../../utils/request替换为清晰稳定的语义化路径如@/api/request，并需在构建工具、TS配置、ESLint、IDE及测试工具中同步配置以保障全链路一致性。
模块别名（Aliases）是解决大型前端工程中路径混乱问题最直接有效的方式。它让 import 语句从冗长、脆弱、难以维护的 ../../../utils/request，变成清晰、稳定、语义明确的 @/api/request 或 ~lib/utils。
为什么 ../../../ 路径是“地狱”？
随着目录层级变深，相对路径极易出错：移动文件后 import 全挂；重构时不敢改目录结构；新人看不懂路径指向哪；IDE 自动导入经常选错目标；单元测试里路径逻辑更难对齐。
模块别名把路径解析从“靠人脑数点数”变成“由配置统一映射”，从根本上切断路径与物理位置的强耦合。
主流构建工具的别名配置方式
不同工具写法略有差异，但核心都是声明一个前缀到实际目录的映射关系：
-
Vite：在
vite.config.ts的resolve.alias中配置，支持对象或数组形式，推荐用path.resolve()确保路径准确 -
Webpack：在
resolve.alias中配置，注意值必须为绝对路径（可用path.resolve(__dirname, 'src')） -
TS + VS Code：仅配构建工具还不够，需同步在
tsconfig.json的compilerOptions.paths中声明别名，并启用baseUrl（通常设为"./"），否则 TS 类型检查和跳转会失效
设计别名时的关键实践
别名不是越多越好，应兼顾语义性、稳定性和团队共识：
- 用
@/指向src/—— 最常用，替代../../src/xxx - 用
@api/指向src/api/、@components/指向src/components/—— 细化领域，提升可读性 - 避免用单字母（如
~）或泛义词（如core），除非全团队明确约定其含义 - 别名值目录建议存在且不为空，避免“空映射”导致误导入或类型丢失
配套工作不能少
只配别名，不配其他环节，容易出现“运行正常、编辑报错”或“跳转失败”的割裂体验：
- ESLint：启用
import/resolver插件并配置别名，使import/order和路径校验生效 - Prettier / IDE：确保自动导入（Auto Import）功能识别别名，VS Code 需确认
js/ts.preferences.importModuleSpecifier设为relative或non-relative并匹配别名规则 - 单元测试（如 Vitest / Jest）：Jest 需在
moduleNameMapper中同步别名；Vitest 默认继承 Vite 别名，但若用test.environmentOptions等特殊配置，需额外验证
模块别名本身不复杂，但它像一条引线，牵动着开发、构建、类型、测试多个环节。配置一次，长期受益——路径清晰了，协作顺了，重构也敢动手了。
