TypeScript绝对导入失效：无法找到模块'entities'的解决方法

问题场景 #

你的项目结构如下：

src/
├── entities/
│   ├── index.ts
│   └── Address.ts
└── initializers/
    └── getLoaders.ts

在getLoaders.ts中尝试用import {Address} from "entities"导入时，抛出错误Error: Cannot find module 'entities'，但使用相对路径../entities能正常导入。entities/index.ts已正确导出Address：

export { Address } from "./Address"

当前tsconfig.json配置如下：

{
  "compilerOptions": {
    "target": "es2017",
    "module": "commonjs",
    "lib": [
      "dom",
      "es6",
      "es2017",
      "esnext.asynciterable"
    ],
    "skipLibCheck": true,
    "sourceMap": true,
    "outDir": "./dist",
    "moduleResolution": "node",
    "removeComments": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "resolveJsonModule": true,
    "baseUrl": "./src",
    "paths" : {
    },
    "typeRoots": [
      "./src/custom_typings",
      "./node_modules/@types",
    ],
  },
  "exclude": [
    "node_modules"
  ],
  "include": [
    "src/**/*.ts",
    "**/*.ts"
  ]
}

修复方案 #

1. 完善tsconfig的paths映射 #

你已经设置了baseUrl: "./src"作为绝对导入的基础，但缺少paths配置来映射entities别名。修改compilerOptions.paths：

"paths": {
  "entities": ["./entities/index.ts"],
  "entities/*": ["./entities/*"]
}

• "entities": ["./entities/index.ts"]：让import "entities"直接指向entities目录的入口文件
• "entities/*": ["./entities/*"]：支持后续可能的子模块导入（如import X from "entities/XXX"）

2. 处理运行时的模块解析 #

TypeScript的paths仅在编译阶段生效，Node.js运行时无法识别这个配置，需要额外处理：

• 用ts-node运行：安装tsconfig-paths依赖，然后用以下命令启动：

  ts-node -r tsconfig-paths/register src/initializers/getLoaders.ts
  

• 编译后运行：如果是编译到dist目录后运行，需要用tsconfig-paths生成运行时路径映射，或者使用打包工具（如Webpack的tsconfig-paths-webpack-plugin）处理路径。

3. 验证配置 #

修改完tsconfig.json后，重启你的IDE（比如VS Code）确保配置刷新生效。此时再尝试import {Address} from "entities"，TypeScript应该不会再报错，运行时也能正确加载模块。

关键说明 #

• baseUrl设置为./src后，TypeScript会把src作为模块解析的根目录，paths是给根目录下的文件夹设置别名。
• 前端项目（如Vite、Create React App）通常会自动兼容tsconfig的paths，但Node.js后端项目必须额外处理运行时的路径解析。

内容的提问来源于stack exchange，提问作者sev