TypeScript Node.js中@src模块解析失效问题求助

TypeScript 的 compilerOptions.paths 仅作用于编译器和 IDE 的路径解析，Node.js 运行时并不识别 @src 这类自定义别名，所以会出现编译无报错但运行时找不到模块的问题。

场景1：用 ts-node 直接运行 TypeScript 代码 #

• 安装依赖：

  npm install -D tsconfig-paths
  

• 修改启动命令，通过 tsconfig-paths/register 来解析别名：

  ts-node -r tsconfig-paths/register src/index.ts
  

• 也可以在 package.json 的 scripts 里配置快捷启动：

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

场景2：编译为 JavaScript 后运行 #

• 安装依赖：

  npm install module-alias
  

• 在项目根目录的 package.json 中添加与 tsconfig 匹配的别名映射：

  "_moduleAliases": {
    "@src": "./dist"
  }
  

  注：./dist 是 TS 编译后的输出目录，需与 tsconfig 中 outDir 配置一致；若未设置 outDir，默认 JS 文件会生成在 TS 文件同目录，此时改为 ./src 即可。
• 在入口文件（如 src/index.ts）的最顶部引入并注册别名解析：

  import 'module-alias/register'
  

• （推荐）在 tsconfig 中明确配置输出目录，避免文件混乱：

  "compilerOptions": {
    "outDir": "./dist",
    // 其他原有配置...
  }
  

额外优化：调整 tsconfig 配置 #

当前 baseUrl 设为 ./src 容易造成路径混淆，建议改为项目根目录，让映射逻辑更直观：

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@src/*": ["src/*"]
    },
    "allowJs": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

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