发布 javascript es modules 的核心做法是配置 package.json 中的 exports 字段,并配合构建工具将源码编译为浏览器和 node.js 都能识别的格式。你需要确保入口文件导出的是符合规范的模块代码,同时提供类型定义文件(.d.ts)以支持 typescript 开发者的自动补全。这样既能让现代环境直接加载,也能兼容旧版工具链。

如何配置 package.json 实现多环境兼容
在 package.json 中设置 exports 可以精确控制不同导入路径对应的文件。推荐使用条件导出语法,分别指定 import、require 和 default 场景下的文件路径。这能确保在使用 import 语句时加载 ESM 文件,而使用 require 时加载 CJS 文件,从而覆盖绝大多数运行环境。

{
"name": "my-esm-lib",
"version": "1.0.0",
"type": "module",
"main": "./dist/cjs/index.cjs",
"module": "./dist/esm/index.mjs",
"types": "./dist/types/index.d.ts",
"exports": {
".": {
"import": {
"types": "./dist/types/index.d.ts",
"default": "./dist/esm/index.mjs"
},
"require": {
"types": "./dist/types/index.d.ts",
"default": "./dist/cjs/index.cjs"
}
},
"./utils": {
"import": "./dist/esm/utils.mjs",
"require": "./dist/cjs/utils.cjs"
}
}
}
上述配置展示了标准的导出结构。根路径 . 对应默认导入,子路径 ./utils 允许按需引入。每个条件都优先声明了 types,这样 TypeScript 编译器在解析模块时能直接找到类型声明,无需额外配置 @types 包。实际发布时,需确保 dist 目录已生成对应的文件。
立即学习“Java免费学习笔记(深入)”;
FilePond 是一个 JavaScript 文件上传库,支持通过拖拽、粘贴和 API 方式处理文件、目录、URL 和 Data URI。它包含内置的图像优化功能、异步分块上传功能,并提供了适用于 React、Vue、Angular 和 Svelte 的适配器。
构建流程中如何处理源码与输出
开发者通常使用 Rollup 或 Vite 等工具将 TypeScript 源码打包。关键在于配置输出格式,同时生成 ESM 和 CJS 两种产物。Rollup 的 output 选项支持数组形式,可以一次性输出多个格式的文件。需要特别注意,ESM 文件应使用 .mjs 扩展名,CJS 文件使用 .cjs,以避免混淆。

// rollup.config.js
export default {
input: 'src/index.ts',
output: [
{
file: 'dist/esm/index.mjs',
format: 'esm',
sourcemap: true,
exports: 'named'
},
{
file: 'dist/cjs/index.cjs',
format: 'cjs',
sourcemap: true,
exports: 'named'
}
],
plugins: [typescript()],
external: ['react']
};
该配置示例中,format: 'esm' 生成浏览器友好的模块,format: 'cjs' 生成 Node.js 兼容的模块。external: ['react'] 确保第三方库不被打包进最终文件,保持库的轻量级。构建完成后,生成的文件结构应与 package.json 中的 exports 映射一致。
发布时如何处理类型定义文件
类型定义文件(.d.ts)是 ES Modules 发布的重要组成部分。它们不应包含运行时逻辑,仅用于静态类型检查。在构建过程中,可以使用 tsc --declaration 或 rollup-plugin-dts 从源码生成类型文件。这些文件应放置在 dist/types 目录下,并在 package.json 中通过 types 字段或 exports.types 指向它们。
如果项目使用纯 JavaScript 而非 TypeScript,可以通过 JSDoc 注释提供类型信息,或使用 api-extractor 等工具生成 .d.ts 文件。确保类型文件的结构与源代码完全对应,避免导出未实现的接口。发布前,建议在一个新项目中安装该库,验证类型提示是否正常工作,以及导入路径是否正确解析。

















