模块路径别名应统一配置于构建工具原生入口并同步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 配置，容易导致类型检查与运行时路径不一致

别名命名需语义化且收敛，避免泛滥

别名不是越多越好，应聚焦高频、跨层级复用的目录，常见推荐模式：

javascript-pro

专注现代 ECMAScript、异步编程、性能优化和全栈的 JavaScript 专家，适用于现代开发

下载

• @/ → 指向 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 启动方式被正确使用