ethers.js 浏览器分发包（dist）完全指南：ESM 产物、词表优化与构建管线

区块链Web3【免费下载链接】ethers.jsComplete Ethereum library and wallet implementation in JavaScript.项目地址https://gitcode.com/gh_mirrors/et/ethers.js点击查看免费下载本篇技术指南以仓库内 misc/basedirs/dist/README.md 为骨架深入讲解 ethers.js 的浏览器分发目录dist它面向 ESM 浏览器项目提供开箱即用的打包产物为了控制体积主包只内置英文助记词词表其余语言词表通过wordlists-extra.js按需加载。读完本文你将掌握 dist 目录的产物构成、词表裁剪原理、从 TypeScript 源码到浏览器产物的完整构建流程以及为何不能手改 dist、该去哪里改的维护约定。一、dist 文件夹的定位面向浏览器 ESM 的分发产物在 ethers.js 仓库根目录下dist/是一个独立于lib.commonjs/CommonJS 产物与lib.esm/ESM 产物之外的第三类产物目录。根据 misc/basedirs/dist/README.md 的说明该目录的内容专门用于在浏览器基browser-base的 ESM 项目中通过import使用。换句话说dist不是给 Node.js 后端或打包器内部使用的中间产物而是可以直接被script typemodule标签或 CDN 引用的最终浏览器包lib.commonjs/面向require()的 CommonJS 项目其说明见 misc/basedirs/lib.commonjs/README.mdlib.esm/面向 Node ESM 的import其说明见 misc/basedirs/lib.esm/README.mddist/则是把 ESM 代码进一步 Rollup 打包、去除 Node 专属依赖后的浏览器专用产物。从当前仓库的实际文件列表可以确认dist/ 目录内包含如下内容文件说明ethers.js浏览器 ESM 格式主包含 sourcemapethers.js.mapethers.min.js经 uglify-js 压缩的主包ethers.umd.jsUMD 格式包暴露全局ethers含ethers.umd.js.mapethers.umd.min.js压缩后的 UMD 包wordlists-extra.js附加词表包含wordlists-extra.js.mapwordlists-extra.min.js压缩后的附加词表包README.md即本文主题文档其中ethers.js与ethers.min.js只包含英文词表以节省空间这是 dist 目录最核心的设计决策下一节详细展开。二、词表体积优化为什么主包只带英文词表README 明确指出Theethers.js(andethers.min.js) files only include the English wordlist to conserve space.这一设计在源码注释中有更量化的说明。查看 src.ts/wordlists/wordlists.tsThe dist files (in the/distfolder) have had all languages except English stripped out, which reduces the library size by about 80kb. If required, they are available by importing the includedwordlists-extra.min.jsfile.也就是说完整版 ethers.js 的wordlists对象注册了10 个词表见 src.ts/wordlists/wordlists.tscz捷克语、en英语、es西班牙语、fr法语、it意大利语、pt葡萄牙语、ja日语、ko韩语、zh_cn简体中文、zh_tw繁体中文与zh_cn共用LangZh实现仅语言标记不同但在打包 dist 主包时除en之外的所有语言词表都被剥离体积因此减少约 80 KB若应用需要多语言 BIP-39 助记词支持则必须额外导入wordlists-extra.js或其压缩版wordlists-extra.min.js。何时必须引入 wordlists-extra.js如果你的应用只生成/校验英文助记词ethers.js已足够无需额外文件如果你需要生成中文、日文、韩文等非英文助记词或需要校验其他语言词表的助记词就必须同时引入wordlists-extra包否则wordlists字典中对应的语言条目缺失相关 API 会因找不到词表而报错。三、dist 产物的真实构建流程从 TypeScript 到浏览器包README 说明 dist 内容由npm build dist目标配合 rollup 与 rollup 配置生成。对照当前仓库 package.json 的实际脚本这一目标就是npm run build-dist其执行链为npm run build-dist # 等价于npm run build npm run _build-dist npm run _dist-stats拆解如下npm run buildtsc --project tsconfig.esm.json把 src.ts/ 下的 TypeScript 源码编译为 lib.esm/ESM 模块npm run _build-distrollup -c依据 rollup.config.mjs 打包再用uglifyjs产出各.min.js压缩版rollup -c uglifyjs ./dist/ethers.js -o ./dist/ethers.min.js uglifyjs ./dist/ethers.umd.js -o ./dist/ethers.umd.min.js uglifyjs ./dist/wordlists-extra.js -o ./dist/wordlists-extra.min.jsnpm run _dist-statsgzip -k9f生成.gz文件并输出各产物体积du -hs用于发布前核对包体大小。rollup 配置解读rollup.config.mjs 中定义了三个输出目标getConfig({ browser: true }), // → dist/ethers.jsESM getConfig({ browser: true, suffix: .umd, format: umd, name: ethers }), // → dist/ethers.umd.js { input: ./lib.esm/wordlists/wordlists-extra.js, // → dist/wordlists-extra.js output: { file: ./dist/wordlists-extra.js, format: esm, sourcemap: true }, ... }几个关键细节输入主包输入为./lib.esm/index.js即 tsc 编译后的 ESM 入口词表附加包输入为./lib.esm/wordlists/wordlists-extra.js这正是主包剥离多余词表、附加包单独携带这一设计在构建侧的落点browser 优先mainFields在浏览器构建时把browser前置mainFields.unshift(browser)配合 package.json 的browser字段映射将 Node 专属模块替换为浏览器实现——包括crypto→crypto-browser.js、provider-ipcsocket→provider-ipcsocket-browser.js、ws→ws-browser.js、base64→base64-browser.js、geturl→geturl-browser.js、wordlists→wordlists-browser.js共 6 组全局环境兜底通过 banner 注入__$G依次回退globalThis → window → global → self并把 Rollup 的context设为__$G保证浏览器、Worker 等不同环境下都能正确取得全局对象treeshake主包启用treeshake: true配合sideEffects: false见 package.json未使用的模块会被摇树剔除进一步压缩体积。四、维护约定不要手改 dist构建时它会被整体删除README 给出了两条明确的维护红线Do not modify the files in this folder. They are deleted onbuild-clean.这背后是 package.json 中clean脚本的逻辑clean: rm -rf dist lib.esm lib.commonjs cp -r misc/basedirs/* .build-clean会先删除 dist连同 lib.esm、lib.commonjs因此任何手工改动都会在下次干净构建时丢失——dist 中的文件只能通过构建生成不得直接编辑被删除的三个目录的种子内容来自 misc/basedirs/内含lib.esm/、lib.commonjs/、dist/三个子目录的 README 与 package.json 模板clean会把这些模板拷贝回仓库根目录再由后续的build/build-commonjs/_build-dist填充真实产物如果你要修改 dist 目录的README.md正确做法是修改其源模板。README 指明/output/post-build/dist从当前仓库看output/ 目录是构建/覆盖率等产出物的落盘位置。同理lib.esm 与 lib.commonjs 下的 README 源模板分别位于/output/post-build/lib.esm与/output/post-build/lib.commonjs见 misc/basedirs/lib.esm/README.md 与 misc/basedirs/lib.commonjs/README.md。五、浏览器中的实际用法根据 README 的定位dist 产物在浏览器 ESM 项目中的典型用法如下。1. 只需英文词表直接引入主包script typemodule import { Wallet } from ./dist/ethers.js; // 或经 CDN 引入 ethers.min.js const wallet Wallet.createRandom(); // 默认使用英文助记词 console.log(wallet.mnemonic.phrase); /script2. 需要多语言助记词额外引入 wordlists-extrascript typemodule import { Wallet, wordlists } from ./dist/ethers.js; import ./dist/wordlists-extra.js; // 注册 en 之外的全部语言词表 const zhList wordlists[zh_cn]; // 简体中文词表 const wallet Wallet.createRandom(zhList); // 生成中文助记词钱包 /script注意wordlists-extra是副作用导入在加载时把额外词表注册进wordlists字典因此示例中以import ./...的方式引入而非按具名导出引入。这与 dist 主包只内置英文、附加包补齐其余语言的设计完全对应。3. 传统全局方式使用 UMD 包若项目未使用模块化加载器可直接引入ethers.umd.js通过全局ethers对象访问 APIscript src./dist/ethers.umd.min.js/script script const wallet ethers.Wallet.createRandom(); console.log(wallet.address); /script六、快速自查清单需要判断某个dist文件能否手改——不能它由npm run build-dist生成且build-clean会整体删除重建需要修改 dist 的 README——去修改/output/post-build/dist对应的模板而非 dist 内的文件浏览器端体积敏感——主包已剥离非英文词表省约 80 KB按需追加wordlists-extra.min.js即可想复现构建——npm run build-dist一条命令即可完成 tsc 编译、rollup 打包、uglify 压缩与 gzip 体积统计Node.js ≥ 14见 package.json。结语dist是 ethers.js 为浏览器 ESM 场景专门设计的最终产物层ethers.js/ethers.min.js面向直接 importethers.umd.js面向全局脚本wordlists-extra.js作为可选的词表补充包。其背后是一套清晰的工程约定——tsc 编译、rollup 打包、uglify 压缩、按语言裁剪词表、构建时整体重建。理解 misc/basedirs/dist/README.md 这份简短说明就等于掌握了这套发布物料的全部使用与维护规则。赞分享区块链Web3【免费下载链接】ethers.jsComplete Ethereum library and wallet implementation in JavaScript.项目地址https://gitcode.com/gh_mirrors/et/ethers.js点击查看免费下载相关推荐ethers.js v6 的 dist 发布目录解析ESM 浏览器构建、词表裁剪与 Rollup 打包流程ethers.js v6 的 dist 发布目录解析ESM 浏览器构建、词表裁剪与 Rollup 打包流程 dist/ 是 ethers.js 面向浏览器端区块链Web3ethers.js 的 ESM 构建产物lib.esm目录职责、生成机制与 import 使用指南ethers.js 的 ESM 构建产物lib.esm目录职责、生成机制与 import 使用指南 本篇指南围绕 ethers.js 仓库中 misc/b区块链Web3深入解析 ethers.js 的 ESM 构建产物lib.esm 目录结构与生成机制深入解析 ethers.js 的 ESM 构建产物lib.esm 目录结构与生成机制 lib.esm/ 是 ethers.js当前仓库版本 6.17.0面区块链Web3上一篇解决JeecgBoot项目中Hikari连接池connectionTestQuery参数设置问题下一篇告别I与І混淆PaddleOCR多语言训练中的字符识别优化终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考