TypeScript枚举键未被转译问题排查求助

搭建了基于TypeScript、Webpack、Babel与React的项目，使用枚举成员作为对象键时出现异常：Webpack编译无报错，但浏览器加载时提示Reference Error: TraitName is not defined。查看转译后代码发现，全局.d.ts文件中定义的字符串枚举TraitName的引用未被替换为对应值，也未被导入。

相关代码片段 #

traits.ts #

import { Trait } from "models/abilities";

const traits: { [key in TraitName]: Trait } = {
  [TraitName.Combat]: new Trait({
    aspect: Aspect.Power,
    name: TraitName.Combat
  }),
  // ...其他枚举成员
}

global.d.ts #

enum TraitName {
  Combat = "Combat",
  // ...其他枚举成员
}

转译后报错代码片段 #

__webpack_require__.r(__webpack_exports__);
/* harmony export */ __webpack_require__.d(__webpack_exports__, {
/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
/* harmony export */ });
/* harmony import */ var models_abilities__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! models/abilities */ "./src/models/abilities/index.ts");

const traits = {
  /* 报错位置 */ [TraitName.Combat]: new models_abilities__WEBPACK_IMPORTED_MODULE_0__.Trait({
    aspect: Aspect.Power,
    name: TraitName.Combat,
    // ...其他属性
  })
}

配置文件 #

tsconfig.json #

{
  "compilerOptions": {
    "target": "es6",
    "outDir": "./build",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": false,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "baseUrl": ".",
    "paths": {
      "data/*": [
        "src/data/*"
      ],
      "models/*": [
        "src/models/*"
      ],
      "presentation/*": [
        "src/presentation/*"
      ],
      "services/*": [
        "src/services/*"
      ],
      "utils": [
        "src/utils"
      ]
    }
  },
  "include": [
    "src"
  ]
}

webpack.config.js #

const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');
const ESLintPlugin = require("eslint-webpack-plugin");

module.exports = {
  entry: path.join(__dirname, "src", "index.tsx"),
  output: {
    path: path.join(__dirname, "build"),
    filename: "[name].[contenthash].bundle.js"
  },
  mode: process.env.NODE_ENV || "development",
  resolve: {
    extensions: [".ts", ".tsx", ".js", ".jsx"],
    plugins: [new TsconfigPathsPlugin({ extensions: [".ts", ".tsx", ".js", ".jsx"] })]
  },
  devServer: {
    port: 3000,
    liveReload: false,
    hot: true
  },
  module: {
    rules: [
      {
        test: /\.js(x)?$/,
        exclude: /node_modules|__tests__/,
        use: ["babel-loader"]
      },
      {
        test: /\.ts(x)?$/,
        exclude: /node_modules|__tests__/,
        use: ["babel-loader"]
      },
      {
        test: /\.css$/,
        exclude: /node_modules/,
        use: ["style-loader", "css-loader"]
      }
    ],
  },
  stats: {
    assets: false,
    builtAt: false,
    moduleAssets: false,
    cachedModules: false,
    runtimeModules: false,
    cachedAssets: false,
    children: false,
    chunks: false,
    context: path.resolve(__dirname, "src"),
    errors: true,
    hash: false,
    logging: "warn",
    modules: false,
    timings: false,
    version: false,
    warnings: true
  },
  plugins: [
    new ESLintPlugin({
      context: "./src",
      extensions: ["ts", "tsx"]
    }),
    new HtmlWebpackPlugin({
      template: path.join(__dirname, "src", "index.html"),
    }),
  ],
};

.babelrc #

{
  "presets": [
      "@babel/env",
      "@babel/react",
      "@babel/preset-typescript"
  ],
  "plugins": [
    "@babel/plugin-proposal-class-properties"
  ]
}

注：曾使用ts-loader加载TypeScript，结果一致，切换为babel-loader未解决问题。

1. .d.ts文件的性质误解：.d.ts仅用于TypeScript类型检查，不会被编译为可执行JavaScript代码。global.d.ts中定义的TraitName只是类型声明，没有对应的运行时代码，浏览器自然找不到该变量。
2. 枚举的类型与运行时分离：当你将枚举成员作为值（而非类型）使用时，TypeScript需要生成对应的JavaScript代码，但由于枚举定义在.d.ts中，编译器不会生成相关运行时代码，导致转译后的代码直接保留TraitName.Combat的引用，无实际变量定义。
3. isolatedModules配置的影响：tsconfig.json中开启了isolatedModules: true，要求每个文件都是独立模块，不允许依赖全局变量。TypeScript类型检查时能识别全局枚举，但编译时不会自动导入或生成相关代码。

方案1：将枚举移到普通.ts文件并导出（推荐） #

把TraitName枚举从global.d.ts转移到普通TypeScript文件（如src/enums/TraitName.ts），并导出：

// src/enums/TraitName.ts
export enum TraitName {
  Combat = "Combat",
  // ...其他枚举成员
}

在traits.ts中导入该枚举：

// traits.ts
import { Trait } from "models/abilities";
import { TraitName } from "enums/TraitName"; // 新增导入

const traits: { [key in TraitName]: Trait } = {
  [TraitName.Combat]: new Trait({
    aspect: Aspect.Power,
    name: TraitName.Combat
  }),
  // ...其他成员
}

此方式能让TypeScript和Babel正确生成枚举的运行时代码，Webpack会将其打包到最终产物中。

方案2：使用字符串字面量类型替代枚举（无运行时代码需求时） #

如果仅需要类型约束，不需要枚举的运行时值，可改用字符串字面量类型：

// global.d.ts
type TraitName = "Combat" | /* 其他字面量 */;

在traits.ts中直接使用字符串作为键：

const traits: { [key in TraitName]: Trait } = {
  Combat: new Trait({
    aspect: Aspect.Power,
    name: "Combat"
  }),
  // ...其他成员
}

此方式完全依赖TypeScript类型检查，不生成任何运行时代码，避免全局变量问题。

方案3：生成全局枚举的运行时代码（不推荐） #

若坚持使用全局枚举，可将枚举定义在普通.ts文件中，添加declare global块，并确保文件被Webpack打包：

// src/globals/TraitName.ts
declare global {
  enum TraitName {
    Combat = "Combat",
    // ...其他成员
  }
}

// 确保文件被视为模块
export {};

在项目入口文件（如index.tsx）中导入该文件：

import "./globals/TraitName";

此方式会在全局作用域生成TraitName变量，但会污染全局命名空间，不推荐在模块化项目中使用。

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