TypeScript枚举特定导入无法加载问题排查

问题描述 #

我把一个TypeScript包发布到NPM，用来在多个TS应用中复用公共枚举值。包构建正常，部分导入方式可以正常运行：

import * as common from 'my-common';
const myEnum: common.enums.MY_ENUM = common.enums.MY_ENUM.ENUM1;
if (myEnum === common.enums.MY_ENUM.ENUM1) {
  console.log('ok');
}

但以下代码编译正常，运行时报错：

import { MY_ENUM } from 'my-common/dist/types/enums';
const myEnum: MY_ENUM = MY_ENUM.ENUM1;
if (myEnum === MY_ENUM.ENUM1) {
  console.log('ok');
}

错误信息：

[1] Provided module can't be loaded.
[1] Did you list all required modules in the package.json dependencies?
[1] Detailed stack trace: Error: Cannot find module 'my-common/dist/types/enums'

我预期my-common/dist/types/enums这种特定导入方式可行，但实际失败。

包中相关文件信息：

• 公共TS文件（describer-common/dist/types/enums.ts）内容：

  export declare enum MY_ENUM {
    ENUM1 = "enum1",
    ENUM2 = "enum2",
    ENUM3 = "enum3",
  }
  

• 包的tsconfig.json内容：

  {
    "compilerOptions": {
      "target": "ES5",
      "strict": true,
      "moduleResolution": "node",
      "esModuleInterop": true,
      "forceConsistentCasingInFileNames": true
    },
    "include": ["src/**/*"]
  }
  

原因与解决办法 #

核心问题 #

1. declare enum仅为类型声明，无运行时代码：你用了export declare enum，这只是TypeScript的类型定义，编译后不会生成对应的JavaScript对象，运行时自然找不到MY_ENUM的实际值。
2. 直接导入dist路径不符合npm包规范：npm包的可导入路径由package.json的main、types、exports字段定义，直接访问dist内部路径属于依赖包的内部实现，发布后可能因文件结构、发布配置问题导致找不到模块。
3. 缺少子路径导出配置：未在package.json中配置子路径导出规则，Node.js运行时无法识别my-common/dist/types/enums这个导入路径。

具体修复步骤 #

1. 修正枚举定义：把declare enum改成普通enum，确保编译后生成运行时可用的JS代码：

   // src/types/enums.ts
   export enum MY_ENUM {
     ENUM1 = "enum1",
     ENUM2 = "enum2",
     ENUM3 = "enum3",
   }
   

2. 配置package.json导出规则：添加main、types、files、exports字段，规范可导入路径并确保发布时包含dist目录：

   {
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "files": ["dist"],
     "exports": {
       ".": "./dist/index.js",
       "./enums": "./dist/types/enums.js",
       "./enums/types": "./dist/types/enums.d.ts"
     }
   }
   

3. 添加包入口文件：在src/index.ts中汇总需要导出的内容，方便用户从包根导入：

   // src/index.ts
   export * from './types/enums';
   

4. 正确的导入方式：修复后，用户可以使用两种简洁的导入方式，不要再直接导入dist路径：

   • 从包根导入：

     import { MY_ENUM } from 'my-common';
     

   • 从子路径导入（基于exports配置）：

     import { MY_ENUM } from 'my-common/enums';
     

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