esbuild-plugin-tsconfig-paths

English | 中文

在 esbuild 构建过程中，将 tsconfig.json 中 compilerOptions.paths 定义的 路径别名转换为相对导入路径。这样无需在运行时处理别名解析，产物更易于分发和使用。

示例

转换前

// src/app/index.ts
import util from "@/utils/util"

转换后

import util from "../utils/util"

安装

npm install esbuild-plugin-tsconfig-paths --dev

使用

import { tsconfigPathsPlugin } from "esbuild-plugin-tsconfig-paths";
import esbuild from "esbuild";

esbuild.build({
    // ...other config
    plugins: [
        // ... other plugins
        tsconfigPathsPlugin({
            // tsconfig 文件所在目录
            cwd: process.cwd(),
            // tsconfig 文件名
            tsconfig: "custom-tsconfig.json",
            // 需要被转换的文件匹配规则
            filter: /.*/,
        })
    ]
})

参数说明

| 参数 | 类型 | 默认值 | 说明 | |------------|-----------|------------------|------------------------------| | filter | RegExp | /.*/ | 匹配需要转换的文件路径。 | | tsconfig | string | tsconfig.json | 指定使用的 tsconfig 文件名。 | | cwd | string | process.cwd() | 查找 tsconfig 的工作目录。 |

注意事项

• 需要在 tsconfig.json 中配置 compilerOptions.paths；baseUrl 默认 ./。
• 在 esbuild 的 onLoad 阶段执行，将匹配到的导入语句改写为相对路径。
• 以 loader: 'ts' 输出，目标为 TypeScript 源码；建议不要让 filter 匹配 .tsx 文件。
• 仅改写静态导入语句；动态导入或非路径规则的解析不会变更。

为什么需要

• 产物不依赖运行时别名解析，部署更简单。
• 源码保持别名的整洁写法，构建后面向消费者的是相对路径。

许可协议

MIT