TypeScript 路径别名消除了深度相对导入（如 ../../../utils/helpers）的痛苦，将其替换为干净的、揭示意图的路径（如 @utils/helpers）。本文涵盖配置、捆绑程序集成、测试和迁移策略。

配置baseUrl和路径

路径别名的基础是 tsconfig.json 中的 paths 映射，与 baseUrl 相结合：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@utils/*": ["./src/utils/*"]
    }
  }
}

baseUrl 设置用于解析非相对模块名称的基目录。 paths 将别名前缀映射到相对于 baseUrl 的文件系统位置。通配符 * 匹配前缀之后的任何路径段。

通配符模式和高级映射

通配符支持灵活的映射策略：

{
  "paths": {
    "@shared/*": ["./src/shared/*"],
    "@components/*": ["./src/components/*", "./src/shared/components/*"],
    "@config": ["./src/config/index.ts"]
  }
}

如果第一个位置不存在，则按顺序搜索多个后备路径。直接模块别名（不带通配符）对于特定入口点非常有用。

捆绑器集成

TypeScript 的 paths 仅影响类型检查和 IDE 支持。每个捆绑器都需要自己的别名配置：

对于 Vite，vite-tsconfig-paths 插件会自动读取您的 tsconfig，从而消除重复：

import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
});

对于 Node.js 运行时解析，请将 tsconfig-paths 包与 tsconfig-paths/register 一起使用。

ESLint 分辨率

如果没有正确的解析器配置，ESLint 的 import/no-unresolved 规则将在别名导入上失败。 eslint-import-resolver-typescript 包自动读取 tsconfig 路径：

settings: {
  'import/resolver': {
    typescript: { alwaysTryTypes: true }
  }
}

您还可以配置 import/order 以单独对别名导入进行分组：

'import/order': ['warn', {
  groups: ['builtin', 'external', 'internal', 'parent', 'sibling'],
  pathGroups: [
    { pattern: '@/**', group: 'internal', position: 'before' }
  ]
}]

单一回购策略

在 monorepos 中，每个包通常都有自己的 tsconfig.json 和路径别名：

• Nx：具有共享路径的根 tsconfig 的项目级 tsconfig
• Turborepo：每个包定义自己的路径；跨包导入的工作区协议
• pnpm 工作区：对于跨包引用，优先使用工作区协议而不是路径别名

TypeScript 项目引用 (composite + references) 提供了 monorepos 中路径别名的替代方案，提供增量编译和更快的构建。

使用路径别名进行测试

测试运行器还需要别名配置：

// Jest - moduleNameMapper
{ "^@/(.*)$": "<rootDir>/src/$1" }

// Vitest - automatically uses Vite's resolve.alias
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
});

迁移策略

逐步采用路径别名。从新代码的单个 @/ 别名开始，然后使用 ts-migrate 等 codemod 或自定义 jscodeshift 转换重构现有导入。迁移后，在 ESLint 中强制使用 import/no-relative-parent-imports 约定。

避免常见的陷阱：使用别名更难发现循环依赖关系，而过度别名（为每个目录创建别名）会增加认知负担，但没有任何好处。

路径别名显着提高了大中型 TypeScript 项目中的代码可维护性。关键的挑战是保持捆绑程序、测试运行程序和 linter 配置同步。使用自动读取 tsconfig 的插件可以大大减轻这种负担。