企业官网建设流程全解析

• 区块链
• Web3

本篇技术指南以仓库内 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 type="module">标签或 CDN 引用的"最终浏览器包"：

• lib.commonjs/面向require()的 CommonJS 项目，其说明见 misc/basedirs/lib.commonjs/README.md；
• lib.esm/面向 Node ESM 的import，其说明见 misc/basedirs/lib.esm/README.md；
• dist/则是把 ESM 代码进一步 Rollup 打包、去除 Node 专属依赖后的浏览器专用产物。

从当前仓库的实际文件列表可以确认，dist/ 目录内包含如下内容：

其中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.ts：

The 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.

也就是说：

1. 完整版 ethers.js 的wordlists对象注册了10 个词表（见 src.ts/wordlists/wordlists.ts）：cz（捷克语）、en（英语）、es（西班牙语）、fr（法语）、it（意大利语）、pt（葡萄牙语）、ja（日语）、ko（韩语）、zh_cn（简体中文）、zh_tw（繁体中文，与zh_cn共用LangZh实现，仅语言标记不同）；
2. 但在打包 dist 主包时，除en之外的所有语言词表都被剥离，体积因此减少约 80 KB；
3. 若应用需要多语言 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

拆解如下：

1. npm run build：tsc --project tsconfig.esm.json，把 src.ts/ 下的 TypeScript 源码编译为 lib.esm/（ESM 模块）；
2. npm run _build-dist：rollup -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.js"

3. npm run _dist-stats：gzip -k9f生成.gz文件并输出各产物体积（du -hs），用于发布前核对包体大小。

rollup 配置解读

rollup.config.mjs 中定义了三个输出目标：

getConfig({ browser: true }), // → dist/ethers.js（ESM） 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 type="module"> import { Wallet } from "./dist/ethers.js"; // 或经 CDN 引入 ethers.min.js const wallet = Wallet.createRandom(); // 默认使用英文助记词 console.log(wallet.mnemonic.phrase); </script>

2. 需要多语言助记词：额外引入 wordlists-extra

<script type="module"> 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对象访问 API：

<script 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面向直接 import，ethers.umd.js面向全局脚本，wordlists-extra.js作为可选的词表补充包。其背后是一套清晰的工程约定——tsc 编译、rollup 打包、uglify 压缩、按语言裁剪词表、构建时整体重建。理解 misc/basedirs/dist/README.md 这份简短说明，就等于掌握了这套发布物料的全部使用与维护规则。

• 区块链
• Web3