构建后带module-alias的npm包TypeScript类型解析失败

你遇到的类型解析问题根源在于：module-alias是运行时路径别名工具，只负责Node.js运行时的路径映射，但TypeScript编译阶段（生成.d.ts类型声明文件时）并不会处理@别名。编译后的dist/index.d.ts里依然保留@/moduleA/file这样的导入路径，其他项目安装包后，由于未配置该别名，TypeScript无法找到对应的类型文件，导致无类型提示、导入错误。

需要让TypeScript编译时识别别名，并且在编译后将所有别名替换为相对路径，确保类型声明文件能被正确解析。

步骤1：配置tsconfig.json的路径别名 #

修改tsconfig.json，添加baseUrl和paths，让TypeScript在编译阶段识别@别名：

{
  "compilerOptions": {
    "baseUrl": "./src", // 基准目录为src
    "paths": {
      "@/*": ["*"] // 映射@/*到src下的所有文件
    },
    "outDir": "./dist", // 输出目录
    "declaration": true, // 生成类型声明文件
    "sourceMap": true, // 生成sourceMap
    "target": "ES2020", // 根据项目需求调整
    "module": "CommonJS" // 根据项目需求调整
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

步骤2：安装tsc-alias处理路径替换 #

TypeScript官方的tsc命令只会做类型检查，不会替换输出文件中的路径别名。需要安装tsc-alias工具，在编译后自动将JS和.d.ts文件中的@别名替换为相对路径：

yarn add tsc-alias --dev
# 或使用npm：npm install tsc-alias --save-dev

步骤3：修改build脚本 #

更新package.json的build脚本，先执行tsc编译，再用tsc-alias替换路径：

{
  "scripts": {
    "build": "rimraf ./dist && tsc && tsc-alias"
  }
}

步骤4：调整运行时别名配置（可选） #

如果编译后已经用tsc-alias替换了所有@为相对路径，其实运行时可以不需要module-alias了。如果保留module-alias，确保config.ts的配置正确：

// src/config.ts
import path from 'path';
import moduleAlias from 'module-alias';
// 构建后__dirname指向dist目录，配置依然有效
moduleAlias.addAlias('@', path.resolve(__dirname));

执行yarn build后，查看dist/index.d.ts，原来的export * from '@/moduleA/file'会被替换为：

export * from './moduleA/file';

此时在其他项目中安装该包，TypeScript就能正确解析类型，获取foo函数和Bar类型的提示了。

内容的提问来源于stack exchange，提问作者Vinicius França