构建TypeScript包后在React前端导入异常，该如何解决？

核心问题排查与修复步骤 #

1. 补全package.json的模块配置 #

你的包缺少package.json中定义模块入口和类型的关键字段，导致React项目无法正确识别导出内容。必须添加以下配置：

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

• main：指定CommonJS格式的入口文件
• module：指定ES模块格式的入口文件
• types：指定TypeScript类型声明文件路径
• files：明确npm发布时包含的目录

2. 修正tsconfig的循环引用错误 #

你当前的tsconfig存在循环引用问题（extends: "./tsconfig.json"），会导致配置失效。正确拆分配置：

• 根目录创建基础tsconfig.json：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

• 创建tsconfig.build.json用于构建：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "noEmit": false,
    "sourceMap": true,
    "outDir": "./dist"
  },
  "exclude": ["src/**/*.test.ts"]
}

新增outDir指定输出目录为dist，同时修正extends指向基础配置。

3. 配置并执行正确的构建命令 #

在包的package.json中添加构建脚本：

{
  "scripts": {
    "build": "tsc --project tsconfig.build.json"
  }
}

执行npm run build后，检查dist目录是否生成index.js、index.d.ts和对应的sourcemap文件。

4. 本地测试时避免模块解析冲突 #

如果用npm link本地测试包，需在React项目的package.json中添加：

{
  "resolutions": {
    "my-package": "file:../path-to-your-package"
  }
}

或者临时用相对路径导入（仅测试场景）：

import { myObject, getKeys } from "../my-package/dist"

5. 验证导出格式正确性 #

构建完成后打开dist/index.js，确认导出代码格式正确：

export const myObject = { a: 1, b: 2 };
export function getKeys() {
    return Object.keys(myObject);
}
export function getValues() {
    return Object.values(myObject);
}

如果输出的是CommonJS格式（用module.exports），需确保React项目的webpack配置支持CommonJS，或在tsconfig中设置module: "ESNext"输出ES模块。

内容的提问来源于stack exchange，提问作者Mertcan Karık