Webpack5+Esbuild-loader下TS枚举值未编译为字面量的问题

核心原因 #

esbuild对环境枚举（declare enum/declare const enum）的处理逻辑和tsc不一样：环境枚举本质是类型声明，esbuild编译时只处理值层面的代码，不会主动解析环境枚举的具体值做替换——哪怕你开了preserveConstEnums也没用，这个配置只对非环境的const enum生效。

解决方案 #

方案1：将环境枚举改为非环境的const enum #

把global.d.ts里的declare enum改成普通const enum，移除declare关键字，同时确保文件在tsconfig的include范围内：

// 修改后的global.d.ts
const enum MyEnum {
   propertyOne = 'value1',
   propertyTwo = 'value2',
   // ... 其他枚举值
}

tsconfig保持preserveConstEnums: false（默认值），esbuild-loader就会直接把MyEnum.propertyOne替换成'value1'。

如果需要保留环境声明对外暴露类型，可以拆分文件：

1. 新建src/enums.ts存放实际枚举值：

   export const enum MyEnum {
      propertyOne = 'value1',
      propertyTwo = 'value2',
   }
   

2. 在global.d.ts里重新声明类型：

   declare enum MyEnum {
      propertyOne = 'value1',
      propertyTwo = 'value2',
   }
   

这样代码里的MyEnum.propertyOne会被esbuild替换为具体值，类型层面也能正常识别。

方案2：配置esbuild-loader的tsconfigOverride #

在webpack配置里给esbuild-loader添加tsconfigOverride，强制开启枚举常量替换：

module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'esbuild-loader',
        options: {
          loader: 'tsx',
          target: 'es2020',
          tsconfigOverride: {
            compilerOptions: {
              preserveConstEnums: false,
              isolatedModules: true,
            },
          },
        },
      },
    ],
  },
};

注意：这个方法仅对非环境的const enum有效，环境枚举还是得用方案1处理。

方案3：换用swc-loader作为替代 #

如果esbuild-loader的枚举处理不符合需求，可以试试swc-loader——它的编译速度和esbuild接近，对枚举的处理更贴近tsc：

1. 安装依赖：

npm install @swc/core swc-loader --save-dev

2. 替换webpack配置中的loader：

module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: {
          loader: 'swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'typescript',
                tsx: true,
              },
              transform: {
                constEnum: {
                  preserveConstEnums: false,
                },
              },
            },
          },
        },
      },
    ],
  },
};

swc会自动替换const enum引用为具体值，对环境枚举的处理也更友好，同时性能和esbuild不相上下。

关键注意事项 #

• isolatedModules: true会让tsc和esbuild默认每个文件是独立模块，环境枚举的跨文件引用无法被解析，必须改成模块内的const enum。
• declaration: true只影响类型声明文件生成，和枚举值的替换逻辑无关。

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