模块路径别名应统一配置于构建工具原生入口并同步tsconfig.json的paths与baseUrl，推荐@/指向src/等语义化收敛命名，避免泛滥；Node运行时需额外借助tsconfig-paths或module-alias支持。
模块路径别名（Alias）能显著提升大型项目中 import 语句的可读性和可维护性，避免冗长、易出错的相对路径（如 ../../../utils/request）。但配置不当反而会带来构建异常、IDE 跳转失败、TS 类型提示丢失等问题。关键在于“统一、收敛、显式”——让别名在开发、构建、类型检查三个环节行为一致。
优先使用构建工具原生支持的 alias 配置
现代构建工具（Vite、Webpack、Rollup）都提供标准 alias 配置入口，应优先使用，而非依赖插件或 hack 方式：
-
Vite：在
vite.config.ts的resolve.alias中定义，天然支持 TS 路径映射（配合tsconfig.json即可启用智能跳转和类型推导） -
Webpack：在
resolve.alias中配置，需同步更新tsconfig.json的compilerOptions.paths，否则 TS 编译器无法识别 -
不建议用
@rollup/plugin-alias单独配置 Rollup 别名而不同步处理 TS 和 IDE 配置，容易导致类型检查与运行时路径不一致
别名命名需语义化且收敛，避免泛滥
别名不是越多越好，应聚焦高频、跨层级复用的目录，常见推荐模式：
-
@/→ 指向src/根目录（最通用，几乎所有项目都适用） -
@/assets/→src/assets/（静态资源） -
@/components/→src/components/（可复用 UI 组件） -
@/hooks/→src/hooks/（自定义 Hook） -
避免为每个子目录都设别名（如
@/components/button/、@/components/input/），这会增加记忆成本且违背别名“降噪”初衷
务必同步配置 tsconfig.json 的 paths 和 baseUrl
TypeScript 不读取构建工具的 alias，必须显式声明才能获得类型检查、自动导入和跳转支持：
立即学习“Java免费学习笔记（深入）”；
- 设置
"baseUrl": "."（或"./src"，需与实际源码根路径一致） - 在
"paths"中严格对齐构建工具中的 alias 映射，例如："@/*": ["src/*"]、"@/assets/*": ["src/assets/*"] - 确保
tsconfig.json被 IDE（VS Code）和构建流程共同加载；若使用多配置（如tsconfig.node.json），需分别配置对应 paths
警惕 Node.js 运行时场景（如 SSR、CLI 工具）的别名失效
Webpack/Vite 的 alias 仅在打包阶段生效，Node 直接运行的脚本（如 node scripts/build.js）默认不识别 @/ 等别名：
- SSR 场景下，服务端代码需借助
ts-node+tsconfig-paths注册别名支持 - 纯 JS 运行时脚本可使用
module-alias（需 require hook 注入），但更推荐在 Node 环境中尽量用相对路径或明确的process.cwd()构建路径 - CI/CD 中执行的脚本若涉及 TS 编译，应确保
ts-node -r tsconfig-paths/register启动方式被正确使用
