TypeScript与Webpack构建后如何将.d.ts绝对路径转相对路径

.d.ts中出现本地磁盘绝对路径的核心原因：

• 项目配置了@/*路径别名，TypeScript在生成声明文件时未对别名做相对路径转换，直接解析为本地绝对路径
• 原配置未指定rootDir，TypeScript自动推导的根目录不符合发布要求，进一步加剧路径异常
• 将类型生成逻辑耦合在webpack打包流程中，导致路径处理逻辑混乱

方案一：分离类型生成流程（推荐，稳定性最高） #

将JavaScript产物打包和TypeScript声明文件生成拆分为两个独立流程，避免webpack构建逻辑干扰类型文件路径计算。

1. 安装依赖 #

npm install typescript-transform-paths --save-dev

2. 调整tsconfig基础配置 #

在原tsconfig.json的compilerOptions中新增路径转换插件配置：

"plugins": [
  { "transform": "typescript-transform-paths" },
  { "transform": "typescript-transform-paths", "afterDeclarations": true }
]

注意：afterDeclarations: true为必选配置，确保声明文件生成后也会执行别名到相对路径的转换。

3. 新增专门用于生成类型的tsconfig文件 #

新建tsconfig.build.json，专门用于输出声明文件，避免和本地开发配置混淆：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "sourceMap": false,
    "outDir": "./lib",
    "rootDir": "./packages",
    "noEmit": false
  },
  "include": ["./packages"],
  "exclude": ["node_modules", "lib", "stories"]
}

核心配置说明：

• rootDir: "./packages"：指定TypeScript编译根目录为组件目录，所有生成的类型文件相对路径都会基于该目录计算，不会出现上层路径引用
• 排除stories目录：避免将文档案例的类型文件发布到私有包，减小包体积

4. 调整构建脚本 #

在package.json的scripts中新增类型生成命令：

"build:types": "tsc --project tsconfig.build.json"

原webpack打包命令保持不变，可添加流程串联命令：

"build": "npm run build:js && npm run build:types"

5. 微调webpack配置 #

移除ts-loader的声明文件生成逻辑，让webpack仅负责打包JavaScript产物：

// ts-loader的options修改为
options: {
  onlyCompileBundledFiles: true,
  transpileOnly: true
}

同时移除原有手写的@别名配置，替换为tsconfig-paths-webpack-plugin保证路径解析和TypeScript配置一致，降低双份配置的维护成本：

npm install tsconfig-paths-webpack-plugin --save-dev

// webpack.config.js顶部引入
const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

// resolve字段修改为
resolve: {
  extensions: ['.ts', '.tsx', '.js', '.svg', '.scss', '.ttf'],
  plugins: [new TsconfigPathsPlugin({})]
}

方案二：保留webpack统一构建流程（改动较小） #

如果不想拆分构建流程，可在原webpack配置中直接添加路径转换逻辑：

1. 安装依赖 #

npm install typescript-transform-paths tsconfig-paths-webpack-plugin --save-dev

2. 调整tsconfig.json #

新增和方案一一致的plugins配置，同时在compilerOptions中新增rootDir: "./packages"，并调整include字段排除非生产目录：

"compilerOptions": {
  // 原有配置保持不变
  "rootDir": "./packages"
},
"include": ["./packages"]

3. 调整webpack.config.js #

和方案一一致，用TsconfigPathsPlugin替换原手写的@别名配置即可。

构建完成后打开lib目录下任意.d.ts文件，检查所有import路径：

• 不会出现/Users/xxx/、D:\xxx\这类本地磁盘绝对路径
• 原@/xxx的别名会被替换为对应相对路径，比如@/Button/Button会被转换为./Button/Button

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