深入解析 ethers.js 的 ESM 构建产物：lib.esm 目录结构与生成机制

区块链Web3【免费下载链接】ethers.jsComplete Ethereum library and wallet implementation in JavaScript.项目地址https://gitcode.com/gh_mirrors/et/ethers.js点击查看免费下载lib.esm/是 ethers.js当前仓库版本 6.17.0面向 ECMAScript ModulesESM生态发布的构建产物目录专供使用import语法的现代 Node.js、打包器与浏览器项目消费。本文以 lib.esm/README.md 为骨架结合仓库中的tsconfig、package.json与构建脚本完整拆解该目录的定位、生成流程、双模块分发策略以及只读产物的维护约定帮助读者理解 ethers.js 的发布体系并在自己的项目中正确选用 ESM 构建。lib.esm 是什么为import而生的 ESM 产物根据 lib.esm/README.md 的说明该目录的全部内容用于在 ESM 项目中使用importThe contents of this folder are for usingimportin ESM projects.这意味着lib.esm/下的每个 JavaScript 文件都采用import/export语法编写并且目录内的 package.json 声明了type: module使 Node.js 在解析该目录下的.js文件时按 ESM 语义处理。与之相对仓库还维护了一个 lib.commonjs/ 目录面向使用require()的 CommonJS 项目。两者在功能上完全等价只是模块语法不同。例如 ESM 入口 lib.esm/index.js 通过export * from ./ethers.js导出全部 API而 CommonJS 入口 lib.commonjs/index.js 则以module.exports形式提供相同内容。这种同一源码、双格式输出的做法正是 ethers.js 兼顾现代与旧有生态的关键设计。双模块分发体系ESM 与 CommonJS 如何共存ethers.js 在根目录 package.json 中通过三层机制实现了模块格式的自动路由顶层字段module: ./lib.esm/index.js指向 ESM 入口供打包器如 webpack、Rollup、Vite优先识别main: ./lib.commonjs/index.js指向 CommonJS 入口作为 Node.js 与旧工具链的默认兜底。条件导出exports根 package.json 的exports字段为每个子模块都配置了双条件例如根入口.: { import: ./lib.esm/index.js, default: ./lib.commonjs/index.js }当运行环境或打包器满足import条件时命中 ESM 产物否则回落到defaultCommonJS。abi、address、constants、contract、crypto、hash、providers、transaction、utils、wallet、wordlists等子模块均遵循同一模式分别映射到 lib.esm/abi/index.js、lib.esm/providers/index.js 等对应入口。目录级 type 声明lib.esm/package.json中的type: module从内部保证.js文件按 ESM 解释即使消费者未通过exports路由也能正确加载。这一套组合使得同一份import代码在不同环境下都能获得符合预期的构建产物无需使用者手动区分路径。构建管线npm run build如何生成 lib.esmREADME 明确指出该目录内容由构建命令生成The contents are generated via thenpm run buildtarget usingtscand the/tsconfig.esm.jsonconfiguration.对应到根 package.json 的 scripts 定义其实际命令为build: tsc --project tsconfig.esm.jsonTypeScript 编译器以 src.ts/ 目录rootDir下的 TypeScript 源码为输入按照 tsconfig.esm.json 的配置输出到./lib.esm。仓库内的完整构建体系还包括Script命令作用buildtsc --project tsconfig.esm.json仅生成 ESM 产物到 lib.esmbuild-commonjstsc --project tsconfig.commonjs.json仅生成 CommonJS 产物到 lib.commonjsbuild-allnpm run build npm run build-commonjs依次生成两种产物auto-buildnpm run build -- -w监听模式源码变更自动重建build-distnpm run build npm run _build-dist npm run _dist-stats先建 ESM再经 Rollup 打包 dist 并统计体积build-cleannpm run clean npm run build node lib.esm/_admin/update-version.js node lib.esm/_admin/update-changelog.js npm run build-all npm run _build-dist npm run _dist-stats全量重建清理、构建、更新版本与变更日志、打包 dist其中tsconfig.commonjs.jsontsconfig.commonjs.json仅将module改为commonjs、outDir指向./lib.commonjs并排除src.ts/_admin/**其余编译选项与 ESM 构建保持一致。编译配置细节tsconfig.esm.json 与共享基础配置tsconfig.esm.json 非常精简只做两处差异化设置其余全部继承 tsconfig.base.json{ extends: ./tsconfig.base.json, compilerOptions: { module: es2020, outDir: ./lib.esm } }基础配置tsconfig.base.json为两种产物提供了统一且严格的编译保证值得关注的选项包括rootDir: ./src.ts以 TypeScript 源码目录为编译根保证产物目录结构abi/、providers/、wallet/等与源码一一对应target: es2022输出目标为 ES2022 语法配合module: es2020生成面向现代引擎的 ESM 代码declaration: true与declarationMap: true每个.js文件旁都生成对应的.d.ts类型声明和声明映射如 lib.esm/wallet/wallet.d.ts这也是lib.esm/中每对*.js/*.d.ts/*.js.map文件的由来sourceMap: true同时产出*.js.map源码映射方便调试时定位回src.ts源码strict: true、noImplicitAny、noImplicitReturns、noUnusedLocals等开启完整严格模式从编译期保障产物质量importHelpers: true引入tslib减少重复的辅助函数代码控制体积对应依赖tslib: 2.7.0。从产物文件结构可以推断tsc将 src.ts/abi/、src.ts/crypto/ 等全部模块编译输出因此lib.esm/下能看到与源码一一对应的abi/、address/、constants/、contract/、crypto/、hash/、providers/、transaction/、utils/、wallet/、wordlists/等子目录及各自的index.js入口。环境差异化browser 字段如何替换平台相关模块lib.esm/package.json中的browser字段定义了浏览器环境下的模块替换规则这是 ESM 产物能在浏览器中正确运行的幕后机制browser: { ./crypto/crypto.js: ./crypto/crypto-browser.js, ./providers/provider-ipcsocket.js: ./providers/provider-ipcsocket-browser.js, ./providers/ws.js: ./providers/ws-browser.js, ./utils/base64.js: ./utils/base64-browser.js, ./utils/geturl.js: ./utils/geturl-browser.js, ./wordlists/wordlists.js: ./wordlists/wordlists-browser.js }根目录 package.json 也以./lib.esm/...前缀维护了完全相同的映射。这意味着密码学与随机数Node 专用的 crypto/crypto.js 在浏览器中被替换为 crypto/crypto-browser.js网络与 WebSocketproviders/ws.js、providers/provider-ipcsocket.js 替换为浏览器版实现IPC 在浏览器中不可用编码与请求Base64、URL 请求等同样提供浏览器替代实现。配合根 package.json 的sideEffects: false声明打包器可安全地对 ESM 产物进行 Tree Shaking按需裁剪未使用的模块。只读产物的约定为什么不要直接修改 lib.esmREADME 中有两条对使用者非常关键的约定Do not modify the files in this folder. They are deleted onbuild-clean.To modify thisREADME.md, see the/output/post-build/lib.esm.含义是lib.esm/是构建产物而非源码任何直接修改都会在下次重建时被覆盖而且build-clean会先执行clean脚本clean: rm -rf dist lib.esm lib.commonjs cp -r misc/basedirs/* .即删除dist、lib.esm、lib.commonjs三个目录后再从 misc/basedirs/ 恢复模板文件。观察 misc/basedirs/lib.esm/ 可以发现其中恰好存放着README.md与package.json两个模板——这正是每次 clean 后lib.esm目录重新出现这两个文件的来源。也就是说clean之后lib.esm/README.md会回到模板内容直到下一次tsc构建才生成完整产物。因此正确的维护姿势是修改 src.ts/ 下的 TypeScript 源码再通过构建命令重新生成产物若确需调整lib.esm的说明文档则应从模板源misc/basedirs/lib.esm/或后续的output/post-build流程入手而不是直接改动产物目录。从 lib.esm 到 dist面向浏览器的最终打包lib.esm不仅直接面向 ESM 使用者还是浏览器单文件构建的输入源。根 package.json 中的_build-dist脚本执行rollup -c uglifyjs ./dist/ethers.js -o ./dist/ethers.min.js ...而 rollup.config.mjs 中getConfig的input: ./lib.esm/index.js表明Rollup 以lib.esm的入口为输入通过nodeResolvemainFields优先browser对lib.esm/package.json的 browser 映射生效后产出dist/ethers.jsESM 格式与dist/ethers.umd.jsUMD 格式全局ethers再由uglifyjs生成.min.js压缩版。也就是说lib.esm处于TypeScript 源码 → 模块化 ESM → 浏览器单文件这条构建链的中间环节。如何在项目中使用 lib.esm在 Node.js 14见根 package.json 的engines字段的 ESM 项目中最简单的用法是直接import顶层入口import { ethers } from ethers; // 或按需引入子模块 import { Wallet } from ethers/wallet; import { JsonRpcProvider } from ethers/providers;现代打包器Vite、Webpack、Rollup 等会自动遵循exports的import条件命中lib.esm从而获得 Tree Shaking 能力。若使用tsc自行编译 ESM 项目且未启用esModuleInterop之外的自动路由也可显式引用仓库路径例如指向 lib.esm/index.js。仓库的测试体系同样验证了 ESM 产物的可用性根 package.json 中test-esm运行mocha ./lib.esm/_tests/test-*.jstest-commonjs则针对lib.commonjs/_tests/运行同一批测试确保两种构建行为一致。开发者可用npm run build重建 ESM 产物、npm run test-esm运行 ESM 侧测试或通过npm run build-clean执行一次清理—重建—版本更新—打包的完整发布演练。小结lib.esm/是 ethers.js 双模块分发体系中的 ESM 半边它由tsc依据 tsconfig.esm.json 从 src.ts/ 编译生成通过根 package.json 的exports/module字段与lib.commonjs协同工作以 lib.esm/package.json 的type: module与browser映射适配不同运行环境并作为 Rollup 浏览器打包的输入源。理解它的生成机制与只读约定既能帮助你在自己的 ESM 项目中正确引用 ethers.js也能在需要定制构建时知道该从何处入手——修改源码而非修改产物。赞分享区块链Web3【免费下载链接】ethers.jsComplete Ethereum library and wallet implementation in JavaScript.项目地址https://gitcode.com/gh_mirrors/et/ethers.js点击查看免费下载相关推荐electron-vue 项目文件树全解开发目录结构与生产构建产物深度剖析electron vue 项目文件树全解开发目录结构与生产构建产物深度剖析 导读 docs/en/file tree.md 是 electron vue 官方桌面应用前端开发工具深入解析 ASP.NET Coreaspnetcore 仓库构建产物 Artifacts 目录结构与使用指南深入解析 ASP.NET Coreaspnetcore 仓库构建产物 Artifacts 目录结构与使用指南 导读 从源码构建 aspnetcore htt后端Web框架三步掌握noteDigger零基础玩转智能音乐扒谱三步掌握noteDigger零基础玩转智能音乐扒谱 noteDigger是一款创新的纯前端音乐扒谱工具通过智能频谱分析技术帮助音乐创作者和爱好者轻松将音频区块链Web3上一篇WeChatFerry 完整指南如何搭建一个可接入大模型的免费微信机器人下一篇Valetudo开源商业模式可持续发展与资金支持创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考