本文详解如何正确配置 typescript 项目以生成可被 webpack/react 直接导入的 es 模块，解决 undefined 导出和 is not a function 等运行时错误。关键在于输出格式、模块解析与入口文件配置。
本文详解如何正确配置 typescript 项目以生成可被 webpack/react 直接导入的 es 模块，解决 undefined 导出和 is not a function 等运行时错误。关键在于输出格式、模块解析与入口文件配置。
要让 TypeScript 编写的库（如 my-package）在 React 前端中正常工作，仅启用 declaration: true 和 noEmit: false 是远远不够的。你遇到的 myObject is undefined 和 WEBPACK_IMPORTED_MODULE_1.getKeys is not a function 错误，根本原因在于：TypeScript 编译器默认生成 CommonJS（CJS）模块代码，而现代前端构建工具（如 Webpack/Vite）期望的是 ESM（ECMAScript Module）格式，并依赖正确的 package.json 入口字段进行模块解析。
✅ 正确构建步骤
1. 配置 tsconfig.json 输出为 ESM
确保编译目标为现代 JavaScript，并显式指定模块系统：
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext", // ← 关键：生成 ES 模块语法（import/export）
"lib": ["ES2020", "DOM"],
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true, // 兼容 CJS 依赖（推荐保留）
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "NodeNext" // ← 关键：启用 Node.js 的 ESM 解析规则
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.test.ts"]
}⚠️ 注意："module": "ESNext" + "moduleResolution": "NodeNext" 是 ESM 支持的前提；"target": "ES2020" 确保语法兼容主流浏览器。
2. 设置 package.json 的模块入口
在 my-package/package.json 中明确声明 ESM 入口，让打包工具优先加载 .mjs 或 exports 字段：
立即学习“前端免费学习笔记（深入）”；
{
"name": "my-package",
"version": "1.0.0",
"types": "./dist/index.d.ts",
"main": "./dist/index.js", // CommonJS 入口（兼容旧环境）
"module": "./dist/index.js", // ← ESM 入口（Webpack 传统用法）
"exports": {
".": {
"import": "./dist/index.mjs", // ← 推荐：显式 .mjs 入口（Vite/Webpack 5+ 优先）
"require": "./dist/index.js"
}
},
"typesVersions": {
"*": {
"dist/*": ["dist/*"]
}
}
}✅ 构建后，确保 dist/ 下存在：
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
- index.js（ESM 格式，含 export const myObject = ...）
- index.mjs（可选，但更明确；可通过 tsc + cp 或 rollup 生成）
- index.d.ts（类型定义）
3. 构建命令建议
使用 tsc 直接构建（无需额外打包工具）：
# 清理并构建
npx tsc --build --clean && npx tsc
# 或添加 script 到 package.json
"scripts": {
"build": "tsc --build"
}构建完成后，验证 dist/index.js 内容是否为标准 ESM：
// dist/index.js（应为如下格式，非 require/module.exports）
export const myObject = { a: 1, b: 2 };
export function getKeys() {
return Object.keys(myObject);
}
export function getValues() {
return Object.values(myObject);
}4. 在 React 中安全导入
确保 React 项目已启用 ESM 支持（Create React App ≥ 5.0 / Vite / Webpack 5+ 默认支持）：
// ✅ 正确导入（自动解析 exports.import）
import { myObject, getKeys } from 'my-package';
console.log(myObject); // {a: 1, b: 2}
console.log(getKeys()); // ['a', 'b']? 如果使用较老的 CRA（< 5.0），可能需升级或启用 --experimental-modules；Vite 用户无需额外配置。
? 常见陷阱排查
- ❌ module: "CommonJS" → 生成 module.exports，前端无法解构导入；
- ❌ 缺少 "type": "module" 或 exports 字段 → 工具回退到 CJS 解析；
- ❌ outDir 与 rootDir 路径错误 → 导致 dist 为空或未生成 .d.ts；
- ❌ tsconfig.json 被 extends 覆盖 → 检查继承链中 module 是否被重写。
✅ 总结
TypeScript 库要在前端可靠运行，核心是 “输出 ESM + 正确声明入口 + 类型对齐”。不要依赖 IDE 的类型提示（它只读 .d.ts），而要验证最终 dist/ 中的 JS 文件是否真正包含 export 语句。构建后建议手动检查 dist/index.js 内容，并在 React 项目中 console.log 验证导出值——这是最直接有效的验证方式。
