[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 baseUrl
• 关系笔记: TypeScript 中的 baseUrl 与 paths

TypeScript 中的 paths

一句话定义

paths 用来把特定 import 模式映射到一组明确的目标路径。

核心机制 / 工作原理

例如：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

这会让 TypeScript 把：

import { foo } from "@/foo";

理解成对 ./src/foo 的解析。

最小例子 / 最小场景

paths 常见于：

• 前端项目 alias
• monorepo 中的局部包内 alias
• IDE 辅助解析

边界与易混淆点

paths 不会改写 emit 出来的 import

这是它最容易被误解的地方。

TypeScript 官方文档明确强调：paths 只影响解析，不会自动改写输出代码里的 import 路径。

所以如果运行时或 bundler 没配同样的 alias，常见结果是：

• 类型检查通过
• 运行时报错

paths 在 monorepo 里容易把别的源码拉进 program

如果 paths 直接跨包指向别人的 src，很容易引发：

• rootDir 报错
• 类型噪音
• IDE 变慢

参考信息

• TSConfig paths: https://www.typescriptlang.org/tsconfig/paths.html