TypeScript 路径别名（Aliases）：从配置到实战，告别复杂相对路径

概述

在 TypeScript 项目里，引用模块是天天都要干的事——尤其项目一大、目录层级一深（比如 src/api/models/user.ts），要是还用老式的相对路径去引，经常就会写出 ../../../../api/models/user 这种”路径嵌套地狱”：写的时候容易把 ../ 数错，后面要是挪了目录，还得一个个文件去改路径，既费事又难维护。

路径别名（Path Aliases）干的就是这件事：把又臭又长的相对 / 绝对路径映射成一个简短的自定义别名（比如用 #api/_ 代替 src/api/_），让模块引用更干净、更好读，也顺带减少了以后重构目录时要改的路径数量。

一、路径别名到底好在哪

比起直接写相对路径，配个路径别名能解决下面这几个实实在在的问题：

1. 路径写起来省事：用 #utils/request 代替 ../../../utils/request，不用再费劲数有几个 ”../” 了；
2. 代码更好维护：以后要是目录结构调整了（比如 src/api 搬到了 src/services/api），只改别名配置就行，不用去每个文件里改引用路径；
3. 团队写法统一：一起协作的时候，定一套统一的别名规则（比如 #components/_ 对应组件、#hooks/_ 对应钩子函数），大家写路径就不会五花八门；
4. 多环境都能跑：配得合理的话，TypeScript 编译识别、Node.js 运行时解析、构建工具（比如 Webpack/Vite）打包，都能一块儿满足。

二、主流实现方案对比

实现 TypeScript 路径别名有好几种方式，核心差别在”要不要依赖第三方库”和”支持什么运行环境”，下面把三种常见方案放一起对比一下：

方案	核心依赖	支持场景	优点	缺点
Node.js 原生 Import Maps	无（Node.js ≥16.14）	Node.js 运行时（CommonJS/ESModule）	无需安装第三方库，原生支持	不兼容浏览器，需 Node.js 版本较高
tsconfig-paths	tsconfig-paths 库	TypeScript 编译 / Node.js 运行时	仅需配置 tsconfig.json，简单直接	需额外安装依赖，运行时需加载库
module-alias	module-alias 库	Node.js 运行时（CommonJS 为主）	支持动态修改别名，兼容性好	对 ESModule 支持较弱，需额外配置

建议优先用 Node.js 原生 Import Maps：不用装第三方包，配置简单，而且 require 和 import 两种导入方式都能支持，也符合未来的标准化趋势（前提是确保 Node.js 版本 ≥16.14，或者低版本用 —experimental-import-maps 标志开启）。

三、实战配置：Node.js 原生 Import Maps 方案

下面以”把项目根目录下的所有文件都映射成 ##/* 别名”为例，完整地讲一遍编译时（TS 识别）和运行时（Node.js 解析）该怎么配。

前提条件

• Node.js 版本 ≥16.14（原生就支持 Import Maps，不用开实验性标志）；
• TypeScript 版本 ≥4.1（支持 tsconfig.json 的 paths 配置）。

步骤 1：配置 tsconfig.json（让编译时认得别名）

TypeScript 编译器得靠 compilerOptions 里的 baseUrl 和 paths 配置才能认出你自定义的别名（不然就会报”模块找不到”的错）。

{
  "compilerOptions": {
    "target": "ES2020", // 根据项目需求设置，建议不低于 ES2020
    "module": "ESNext", // 支持 ESModule，与 Node.js 原生 Import Maps 兼容
    "moduleResolution": "Node", // 按 Node.js 规则解析模块
    "baseUrl": ".", // 别名的基础路径（"." 表示项目根目录）
    "paths": {
      "##/*": ["./*"] // 别名规则："##/xxx" 映射到 "./xxx"
      // 可扩展更多别名，例如：
      // "#src/*": ["src/*"],   // "#src/api" → "src/api"
      // "#utils/*": ["src/utils/*"] // "#utils/request" → "src/utils/request"
    },
    "outDir": "./dist", // 编译输出目录（可选，根据项目结构调整）
    "strict": true // 开启严格模式（推荐，提升代码质量）
  },
  "include": ["src/**/*", "test/**/*"], // 需要 TS 编译的文件目录
  "exclude": ["node_modules"] // 排除 node_modules，避免编译冗余
}

关键配置说明：

• baseUrl：这个必须配，它是 paths 里那些别名映射的”基准路径”，一般设成项目根目录（.）；
• paths：是个对象，键是”别名模式”（里面得带个 * 通配符，表示匹配任意子路径），值是对应的真实路径数组（数组支持写多个备选路径，按顺序找）。

步骤 2：配置 package.json（让运行时解析别名）

TypeScript 编译完之后，Node.js 运行时本身是不认 tsconfig.json 里那个别名的，得靠 package.json 的 imports 字段（也就是原生的 Import Maps 功能）来配运行时的路径映射。

{
  "name": "ts-alias-demo",
  "version": "1.0.0",
  "type": "module", // 关键：声明项目为 ESModule 类型（支持 import/export）
  "imports": {
    "##/*": "./*" // 与 tsconfig.json 的 paths 规则保持一致："##/xxx" → "./xxx"
    // 扩展别名示例（需与 tsconfig.json 对应）：
    // "#src/*": "./src/*",
    // "#utils/*": "./src/utils/*"
  },
  "scripts": {
    "dev": "node src/index.ts", // 直接运行 TS 文件（需安装 ts-node，或编译后运行 dist）
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {},
  "devDependencies": {
    "typescript": "^5.5.0"
  }
}

关键注意事项：

1. 必须加上 “type”: “module”：Node.js 默认是 CommonJS 模块系统，得显式声明成 ESModule，才能启用 imports 字段的 Import Maps 功能；
2. 别名规则得和 tsconfig.json 完全一致：保证编译时和运行时的路径映射逻辑一样，免得出现”编译不报错、运行时却报错”的情况；
3. 如果你的项目是 CommonJS 类型（没有 “type”: “module”）：可以在 package.json 里用 exports 字段代替 imports，规则差不多：

"exports": {
  "##/*": "./*"
}

步骤 3：别名使用示例

配置完之后，就能在 TypeScript 文件里用别名引模块了，下面是几个常见场景的例子：

1. 引用根目录下的文件

假设项目根目录有 api/models.ts 文件，传统相对路径得根据当前文件位置写 ../api/models，用别名直接写 ##/api/models 就行：

// src/index.ts
import { UserModel } from "##/api/models.js"; // 注意：ESModule 需加 .js 后缀（或配置 extensions）

const user = new UserModel({ name: "TypeScript", age: 10 });
console.log(user);

2. 引用 src 目录下的工具函数

如果扩展了 #src/_ 别名（映射 src/_），引 src/utils/request.ts 时就变成：

// src/components/Login.tsx
import { request } from "#src/utils/request.js";

async function login(data: { username: string; password: string }) {
  return await request({
    url: "/api/login",
    method: "POST",
    data,
  });
}

四、常见问题与解决方案

问题 1：TypeScript 编译后，运行时提示 “Cannot find module ’##/api/models’”

原因：tsconfig.json 只配了编译时的别名，Node.js 运行时没认出来（忘了配 package.json 的 imports 字段）。 解决方案：检查一下 package.json 里有没有加 imports 字段，并且别名规则要和 tsconfig.json 保持一致。

问题 2：使用 ESModule 时，引用别名模块需加 .js 后缀，否则报错

原因：ESModule 规范本来就要求写完整的文件后缀（比如 .js），TypeScript 编译后会把 .ts 转成 .js，但开发时引用就得显式写 .js。 解决方案：

1. 开发时按规范把 .js 后缀加上（推荐，这才符合 ESModule 标准）；
2. 要是实在不想写后缀，可以在 tsconfig.json 里配 compilerOptions.extensions，再在 package.json 的 imports 里加上通配符支持（比如 ”##/”: ”./.js”），不过得留意兼容性。

问题 3：项目使用 Webpack/Vite 构建，别名不生效

原因：构建工具（比如 Webpack）有自己的别名解析逻辑，不会自动去读 tsconfig.json 或者 package.json 的配置。 解决方案：在构建工具的配置里把别名规则也同步上，拿 Vite 举例：

// vite.config.ts
import { defineConfig } from "vite";
import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "##/": `${path.resolve(__dirname, ".")}/`, // 与 TS 别名一致
      "#src/": `${path.resolve(__dirname, "src")}/`,
    },
  },
});

问题 4：Node.js 版本低于 16.14，无法使用原生 Import Maps

解决方案：改用 tsconfig-paths 这个第三方库，步骤是这样：

1. 装依赖：npm install tsconfig-paths —save-dev；
2. 在 tsconfig.json 里保持 baseUrl 和 paths 不变；
3. 改一下运行脚本（通过 ts-node 把 tsconfig-paths 加载进来）：

"scripts": {
  "dev": "ts-node -r tsconfig-paths/register src/index.ts"
}

五、最佳实践：别名命名规范

为了避免别名冲突、提升团队协作效率，建议照着下面这套命名规范来：

1. 用特殊前缀把别名区分开：比如用 # 或者 @ 开头（像 #src/、@utils/），免得跟第三方包名撞车；
2. 按目录功能来命名：别名最好能体现出对应目录是干啥的，例如： #src/：项目源代码根目录； #components/：UI 组件目录； #hooks/：React/Vue 钩子函数目录； #api/：接口请求相关文件； #utils/*：工具函数目录；
3. 别把别名嵌套得太深：比如不建议配成 #src/api/models/，直接用 #api/models/ 更清爽；
4. 团队统一配置：把别名规则写进项目文档，保证所有成员用的都是同一套别名映射。