web3.js 4.x 包体积优化实战按官方 Tree Shaking 指南裁剪依赖的完整教程【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js本文对应仓库文档 docs/docs/guides/13_advanced/tree_shaking.md是 web3.js 官方向导中高级Advanced章节下的 Tree Shaking 支持指南。web3.js 4.x 采用 monorepo 模块化架构把全部功能打包进一个总包会显著增大产物体积本指南将带你通过四个明确步骤开启 production 模式、声明 sideEffects、升级 tsconfig 模块标准、按需引入子包让打包器准确剔除未使用代码并给出可复用的 webpack 配置与验证方法帮助你为 DApp 构建出最小化的生产包。为什么 Tree Shaking 对 web3.js 如此重要模块化架构带来的体积挑战web3.js 4.x 不再是一个单一的大库而是由分布在 packages/ 下的十几个独立子包组成的 monorepo。以总包 packages/web3/package.json 的dependencies为例它依赖了web3-core、web3-eth、web3-eth-abi、web3-eth-accounts、web3-eth-contract、web3-eth-ens、web3-eth-iban、web3-eth-personal、web3-net、web3-providers-http、web3-providers-ws、web3-rpc-methods、web3-rpc-providers、web3-types、web3-utils、web3-validator等 16 个以上的运行时依赖。更关键的是总包的入口 packages/web3/src/index.ts 会把所有子模块统一 re-export既有export { Web3Eth } from web3-eth这样的具名导出也有export * as core from web3-core、export * as utils from web3-utils、export * from web3-types这类全量再导出。从源码结构可以推断如果你只从web3这一个包导入打包器在无法静态证明哪些导出未被使用时往往会保留大量实际用不到的代码。因此web3.js 官方在13_advanced章节中专门给出了 4 个标准步骤配合打包器尤其是 webpack的 Tree Shaking 能力把用不到的功能从最终 bundle 中剔除。下面我们逐一展开。第一步开启生产模式mode: productionTree Shaking 依赖打包器做静态分析而 webpack 只有在production模式下才会默认启用一连串优化包括代码压缩minification与未使用导出剔除。在项目根目录的webpack.config.js中设置module.exports { mode: production, // ...其余配置 };设置mode: production后webpack 会默认开启5.x 及以上TerserPlugin 代码压缩移除未使用代码、空白与死代码分支optimization.usedExports标记并剔除未被使用的具名导出即 Tree Shaking 的核心机制DefinePlugin注入process.env.NODE_ENV production让依赖库剪掉开发分支逻辑sideEffects标记生效允许跳过未使用模块的整体加载与第二步配合。值得注意的是web3.js 仓库自己在构建浏览器发行版时同样使用production模式共享构建配置 webpack.base.config.js 中写死了mode: production并配置了 packages/web3/webpack.config.js 生成web3.min.js。也就是说官方生产包本身就是按生产模式压缩产物这从侧面印证了该步骤的必要性。第二步在 package.json 中声明 sideEffects在你自己项目的package.json中加入{ name: my-dapp, sideEffects: false }sideEffects: false告诉打包器本项目的模块在导入时不会产生任何副作用不修改全局对象、不注册副作用因此打包器可以安全地跳过未被引用模块的整个加载过程只保留被使用到的导出。需要注意两点如果你有真正的副作用代码例如全局样式import ./global.css、polyfill、全局事件监听应改用数组形式精确声明{ sideEffects: [*.css, ./src/polyfills.ts] }好消息是web3.js 的若干子包已经自带该声明。例如 packages/web3-utils/package.json 第 23 行就明确写了sideEffects: false所以当你从web3-utils按需导入工具函数时打包器可直接跳过未用模块web3-eth等包同样通过module/exports字段提供了可供 tree shaking 的 ESM 产物见 packages/web3-eth/package.json。关于sideEffects更细粒度的语义可参考 webpack 官方 Tree Shaking 指南原文档中亦附有该链接核心结论是声明得越明确剔除得越彻底。第三步将 tsconfig 的 module 设为 ES2015 或更高Tree Shaking 依赖ES Modulesimport/export的静态结构而require()是运行时动态加载无法被静态分析。因此需要把 TypeScript 编译目标调整为 ESM{ compilerOptions: { module: ES2015 } }ES2015及其以上如ES2020、ESNext都会把 TypeScript 编译成标准 ESM 语法使打包器可以逐导出分析依赖图。从 web3.js 仓库自身也能看到这套实践所有子包都同时产出 CJS 与 ESM 两份构建例如 packages/web3/tsconfig.esm.json 将module设置为es2020并把输出写到lib/esm/而总包的 packages/web3/package.json 通过exports字段区分条件exports: { .: { types: ./lib/types/index.d.ts, import: ./lib/esm/index.js, require: ./lib/commonjs/index.js } }这意味着当你用 ESMimport引入 web3.js 时打包器会自动命中import条件的 ESM 产物从而具备 tree shaking 的前提只有当你用require()时才会落入 CJS 产物。仓库的esm_black_box与cjs_black_box两套测试见 packages/web3/test/esm_black_box 与 packages/web3/test/cjs_black_box正是对这两种消费方式的回归验证。第四步按需引入你真正需要的子包这是四步中收益最直接的一步不要从总包web3导入所有功能而是只安装并导入你需要的子包。场景一只需要web3.eth能力原文档给出的示例JavaScript 版本const { Web3Eth } require(web3-eth); // ...直接使用 Web3Eth 实例TypeScript 版本import { Web3Eth } from web3-eth; // ...直接使用 Web3Eth 实例web3-eth提供了与以太坊区块链及智能合约交互的完整能力Web3Eth类见 packages/web3-eth/src/web3_eth.ts。只依赖这一个包就不会把账户、ENS、IBAN、Personal 等模块的代码一并拖入 bundle。场景二只需要web3-utils里的几个函数如果只用到进制转换工具逐个具名导入即可const { numberToHex, hexToNumber } require(web3-utils); // ...import { numberToHex, hexToNumber } from web3-utils; // ...得益于web3-utils自带的sideEffects: false这种按函数导入的方式可以被打包器精确裁剪只保留这两个函数及其传递依赖而不是整个工具库工具函数实现位于 packages/web3-utils/src/converters.ts 等文件。可选子包速查仓库 packages/ 下按功能拆分的可用子包包括web3-eth以太坊交互、web3-eth-contract合约、web3-eth-accounts账户与签名、web3-eth-abiABI 编解码、web3-eth-ensENS、web3-eth-ibanIBAN、web3-eth-personalPersonal 接口、web3-net网络属性、web3-utils工具函数、web3-validator数据校验、web3-providers-http/web3-providers-ws/web3-providers-ipc各类 Provider、web3-rpc-methodsRPC 封装、web3-rpc-providers公共 RPC Provider、web3-core核心上下文与请求管理、web3-errors错误体系、web3-types类型定义、web3-account-abstraction账户抽象等。按需选择最小依赖集是控制包体积的根本手段。完整示例在 React 应用中配置 webpack 启用 Tree Shaking原指南末尾提到官方提供了一个专门演示 Tree Shaking 的 React 示例应用web3js-example-react-app。下面把它对应的四步整合成一个可直接落地的完整配置。1.package.json声明副作用并引入所需依赖{ name: my-web3-dapp, private: true, sideEffects: false, dependencies: { web3-eth: ^4.11.1, web3-utils: ^4.3.3 }, devDependencies: { webpack: ^5, webpack-cli: ^5, ts-loader: ^9, typescript: ^5 } }2.tsconfig.json使用 ESM 模块标准{ compilerOptions: { target: ES2020, module: ES2015, moduleResolution: node, strict: true, esModuleInterop: true, jsx: react } }3.webpack.config.js开启生产模式const path require(path); module.exports { mode: production, // 关键启用压缩与 tree shaking entry: ./src/index.tsx, output: { path: path.resolve(__dirname, dist), filename: bundle.[contenthash].js, }, resolve: { extensions: [.ts, .tsx, .js], }, module: { rules: [ { test: /\.tsx?$/, use: ts-loader, exclude: /node_modules/, }, ], }, // production 模式下 webpack 已默认开启 usedExports // 配合 sideEffects: false 即可实现文件级与导出级双重裁剪 optimization: { usedExports: true, minimize: true, }, };4. 业务代码只导入所需功能import { useEffect, useState } from react; import { Web3Eth } from web3-eth; import { numberToHex } from web3-utils; const web3Eth new Web3Eth(https://eth-mainnet.example.com); export function Balance({ address }: { address: string }) { const [balance, setBalance] useStatestring(); useEffect(() { web3Eth .getBalance(address) .then((wei) setBalance(numberToHex(wei))); }, [address]); return divbalance(hex): {balance}/div; }构建后检查dist/bundle.*.js的大小再对比从web3总包导入的基线版本即可直观看到 Tree Shaking 带来的体积差异。如何验证 Tree Shaking 是否真的生效配置完成后建议从以下角度验证裁剪效果使用打包分析工具web3.js 仓库自身就提供了分析入口 packages/web3/webpack.analyze.js并通过build:web:analyze脚本见 packages/web3/package.json调用生成依赖体积分布报告。你可以用同样的思路接入webpack-bundle-analyzer检查 bundle 中是否还残留未使用的 web3 模块。对比基线分别以从web3导入和从具体子包导入构建两次对比产物大小确认第四步的收益。检查产物内容在压缩产物中搜索未使用模块的特征字符串如eth_personal相关方法名若已消失则说明已被剔除。确认构建链路确认mode为production、package.json中有sideEffects声明、tsconfig 的module为 ES2015 以上、且全程未使用require()引入 web3 相关模块。常见误区与注意事项require()无法触发 Tree Shaking即使mode: production用 CommonJS 引入也无法做导出级静态裁剪。请统一使用 ESMimport并保证 tsconfig 的module不低于ES2015。从总包web3导入会拉入更多依赖由于 packages/web3/src/index.ts 做了命名空间全量再导出从web3导入时很难保证裁剪彻底能直接导入子包就优先导入子包。sideEffects不能盲目声明为false仅当你的模块确实无副作用时才可如此声明有样式、polyfill 等全局副作用的模块要用数组形式精确列出否则可能出现功能被莫名剔除的运行期问题。浏览器直引与打包器无关如果直接以script方式引入 packages/web3/package.json 中的browser产物dist/web3.min.js那是整包 UMD 构建本身不参与 tree shaking只有走 ESM 打包链路才能享受上述优化。小结web3.js 4.x 的模块化架构为包体积优化提供了天然条件开启production模式 → 声明sideEffects: false→ 使用 ES2015 模块标准 → 按需导入具体子包四步缺一不可。本指南的四步配置与源码证据总包的 re-export 结构、各子包的 ESM 产物与sideEffects声明、共享 webpack 生产配置共同保证了你的 DApp 最终只会携带真正用到的 web3 代码在功能完整的前提下拿到尽可能小的生产 bundle。更多细节可回到原始指南 docs/docs/guides/13_advanced/tree_shaking.md 与同目录下的 custom_RPC.md、extend.md 继续探索高级用法。【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
web3.js 4.x 包体积优化实战按官方 Tree Shaking 指南裁剪依赖的完整教程【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js本文对应仓库文档 docs/docs/guides/13_advanced/tree_shaking.md是 web3.js 官方向导中高级Advanced章节下的 Tree Shaking 支持指南。web3.js 4.x 采用 monorepo 模块化架构把全部功能打包进一个总包会显著增大产物体积本指南将带你通过四个明确步骤开启 production 模式、声明 sideEffects、升级 tsconfig 模块标准、按需引入子包让打包器准确剔除未使用代码并给出可复用的 webpack 配置与验证方法帮助你为 DApp 构建出最小化的生产包。为什么 Tree Shaking 对 web3.js 如此重要模块化架构带来的体积挑战web3.js 4.x 不再是一个单一的大库而是由分布在 packages/ 下的十几个独立子包组成的 monorepo。以总包 packages/web3/package.json 的dependencies为例它依赖了web3-core、web3-eth、web3-eth-abi、web3-eth-accounts、web3-eth-contract、web3-eth-ens、web3-eth-iban、web3-eth-personal、web3-net、web3-providers-http、web3-providers-ws、web3-rpc-methods、web3-rpc-providers、web3-types、web3-utils、web3-validator等 16 个以上的运行时依赖。更关键的是总包的入口 packages/web3/src/index.ts 会把所有子模块统一 re-export既有export { Web3Eth } from web3-eth这样的具名导出也有export * as core from web3-core、export * as utils from web3-utils、export * from web3-types这类全量再导出。从源码结构可以推断如果你只从web3这一个包导入打包器在无法静态证明哪些导出未被使用时往往会保留大量实际用不到的代码。因此web3.js 官方在13_advanced章节中专门给出了 4 个标准步骤配合打包器尤其是 webpack的 Tree Shaking 能力把用不到的功能从最终 bundle 中剔除。下面我们逐一展开。第一步开启生产模式mode: productionTree Shaking 依赖打包器做静态分析而 webpack 只有在production模式下才会默认启用一连串优化包括代码压缩minification与未使用导出剔除。在项目根目录的webpack.config.js中设置module.exports { mode: production, // ...其余配置 };设置mode: production后webpack 会默认开启5.x 及以上TerserPlugin 代码压缩移除未使用代码、空白与死代码分支optimization.usedExports标记并剔除未被使用的具名导出即 Tree Shaking 的核心机制DefinePlugin注入process.env.NODE_ENV production让依赖库剪掉开发分支逻辑sideEffects标记生效允许跳过未使用模块的整体加载与第二步配合。值得注意的是web3.js 仓库自己在构建浏览器发行版时同样使用production模式共享构建配置 webpack.base.config.js 中写死了mode: production并配置了 packages/web3/webpack.config.js 生成web3.min.js。也就是说官方生产包本身就是按生产模式压缩产物这从侧面印证了该步骤的必要性。第二步在 package.json 中声明 sideEffects在你自己项目的package.json中加入{ name: my-dapp, sideEffects: false }sideEffects: false告诉打包器本项目的模块在导入时不会产生任何副作用不修改全局对象、不注册副作用因此打包器可以安全地跳过未被引用模块的整个加载过程只保留被使用到的导出。需要注意两点如果你有真正的副作用代码例如全局样式import ./global.css、polyfill、全局事件监听应改用数组形式精确声明{ sideEffects: [*.css, ./src/polyfills.ts] }好消息是web3.js 的若干子包已经自带该声明。例如 packages/web3-utils/package.json 第 23 行就明确写了sideEffects: false所以当你从web3-utils按需导入工具函数时打包器可直接跳过未用模块web3-eth等包同样通过module/exports字段提供了可供 tree shaking 的 ESM 产物见 packages/web3-eth/package.json。关于sideEffects更细粒度的语义可参考 webpack 官方 Tree Shaking 指南原文档中亦附有该链接核心结论是声明得越明确剔除得越彻底。第三步将 tsconfig 的 module 设为 ES2015 或更高Tree Shaking 依赖ES Modulesimport/export的静态结构而require()是运行时动态加载无法被静态分析。因此需要把 TypeScript 编译目标调整为 ESM{ compilerOptions: { module: ES2015 } }ES2015及其以上如ES2020、ESNext都会把 TypeScript 编译成标准 ESM 语法使打包器可以逐导出分析依赖图。从 web3.js 仓库自身也能看到这套实践所有子包都同时产出 CJS 与 ESM 两份构建例如 packages/web3/tsconfig.esm.json 将module设置为es2020并把输出写到lib/esm/而总包的 packages/web3/package.json 通过exports字段区分条件exports: { .: { types: ./lib/types/index.d.ts, import: ./lib/esm/index.js, require: ./lib/commonjs/index.js } }这意味着当你用 ESMimport引入 web3.js 时打包器会自动命中import条件的 ESM 产物从而具备 tree shaking 的前提只有当你用require()时才会落入 CJS 产物。仓库的esm_black_box与cjs_black_box两套测试见 packages/web3/test/esm_black_box 与 packages/web3/test/cjs_black_box正是对这两种消费方式的回归验证。第四步按需引入你真正需要的子包这是四步中收益最直接的一步不要从总包web3导入所有功能而是只安装并导入你需要的子包。场景一只需要web3.eth能力原文档给出的示例JavaScript 版本const { Web3Eth } require(web3-eth); // ...直接使用 Web3Eth 实例TypeScript 版本import { Web3Eth } from web3-eth; // ...直接使用 Web3Eth 实例web3-eth提供了与以太坊区块链及智能合约交互的完整能力Web3Eth类见 packages/web3-eth/src/web3_eth.ts。只依赖这一个包就不会把账户、ENS、IBAN、Personal 等模块的代码一并拖入 bundle。场景二只需要web3-utils里的几个函数如果只用到进制转换工具逐个具名导入即可const { numberToHex, hexToNumber } require(web3-utils); // ...import { numberToHex, hexToNumber } from web3-utils; // ...得益于web3-utils自带的sideEffects: false这种按函数导入的方式可以被打包器精确裁剪只保留这两个函数及其传递依赖而不是整个工具库工具函数实现位于 packages/web3-utils/src/converters.ts 等文件。可选子包速查仓库 packages/ 下按功能拆分的可用子包包括web3-eth以太坊交互、web3-eth-contract合约、web3-eth-accounts账户与签名、web3-eth-abiABI 编解码、web3-eth-ensENS、web3-eth-ibanIBAN、web3-eth-personalPersonal 接口、web3-net网络属性、web3-utils工具函数、web3-validator数据校验、web3-providers-http/web3-providers-ws/web3-providers-ipc各类 Provider、web3-rpc-methodsRPC 封装、web3-rpc-providers公共 RPC Provider、web3-core核心上下文与请求管理、web3-errors错误体系、web3-types类型定义、web3-account-abstraction账户抽象等。按需选择最小依赖集是控制包体积的根本手段。完整示例在 React 应用中配置 webpack 启用 Tree Shaking原指南末尾提到官方提供了一个专门演示 Tree Shaking 的 React 示例应用web3js-example-react-app。下面把它对应的四步整合成一个可直接落地的完整配置。1.package.json声明副作用并引入所需依赖{ name: my-web3-dapp, private: true, sideEffects: false, dependencies: { web3-eth: ^4.11.1, web3-utils: ^4.3.3 }, devDependencies: { webpack: ^5, webpack-cli: ^5, ts-loader: ^9, typescript: ^5 } }2.tsconfig.json使用 ESM 模块标准{ compilerOptions: { target: ES2020, module: ES2015, moduleResolution: node, strict: true, esModuleInterop: true, jsx: react } }3.webpack.config.js开启生产模式const path require(path); module.exports { mode: production, // 关键启用压缩与 tree shaking entry: ./src/index.tsx, output: { path: path.resolve(__dirname, dist), filename: bundle.[contenthash].js, }, resolve: { extensions: [.ts, .tsx, .js], }, module: { rules: [ { test: /\.tsx?$/, use: ts-loader, exclude: /node_modules/, }, ], }, // production 模式下 webpack 已默认开启 usedExports // 配合 sideEffects: false 即可实现文件级与导出级双重裁剪 optimization: { usedExports: true, minimize: true, }, };4. 业务代码只导入所需功能import { useEffect, useState } from react; import { Web3Eth } from web3-eth; import { numberToHex } from web3-utils; const web3Eth new Web3Eth(https://eth-mainnet.example.com); export function Balance({ address }: { address: string }) { const [balance, setBalance] useStatestring(); useEffect(() { web3Eth .getBalance(address) .then((wei) setBalance(numberToHex(wei))); }, [address]); return divbalance(hex): {balance}/div; }构建后检查dist/bundle.*.js的大小再对比从web3总包导入的基线版本即可直观看到 Tree Shaking 带来的体积差异。如何验证 Tree Shaking 是否真的生效配置完成后建议从以下角度验证裁剪效果使用打包分析工具web3.js 仓库自身就提供了分析入口 packages/web3/webpack.analyze.js并通过build:web:analyze脚本见 packages/web3/package.json调用生成依赖体积分布报告。你可以用同样的思路接入webpack-bundle-analyzer检查 bundle 中是否还残留未使用的 web3 模块。对比基线分别以从web3导入和从具体子包导入构建两次对比产物大小确认第四步的收益。检查产物内容在压缩产物中搜索未使用模块的特征字符串如eth_personal相关方法名若已消失则说明已被剔除。确认构建链路确认mode为production、package.json中有sideEffects声明、tsconfig 的module为 ES2015 以上、且全程未使用require()引入 web3 相关模块。常见误区与注意事项require()无法触发 Tree Shaking即使mode: production用 CommonJS 引入也无法做导出级静态裁剪。请统一使用 ESMimport并保证 tsconfig 的module不低于ES2015。从总包web3导入会拉入更多依赖由于 packages/web3/src/index.ts 做了命名空间全量再导出从web3导入时很难保证裁剪彻底能直接导入子包就优先导入子包。sideEffects不能盲目声明为false仅当你的模块确实无副作用时才可如此声明有样式、polyfill 等全局副作用的模块要用数组形式精确列出否则可能出现功能被莫名剔除的运行期问题。浏览器直引与打包器无关如果直接以script方式引入 packages/web3/package.json 中的browser产物dist/web3.min.js那是整包 UMD 构建本身不参与 tree shaking只有走 ESM 打包链路才能享受上述优化。小结web3.js 4.x 的模块化架构为包体积优化提供了天然条件开启production模式 → 声明sideEffects: false→ 使用 ES2015 模块标准 → 按需导入具体子包四步缺一不可。本指南的四步配置与源码证据总包的 re-export 结构、各子包的 ESM 产物与sideEffects声明、共享 webpack 生产配置共同保证了你的 DApp 最终只会携带真正用到的 web3 代码在功能完整的前提下拿到尽可能小的生产 bundle。更多细节可回到原始指南 docs/docs/guides/13_advanced/tree_shaking.md 与同目录下的 custom_RPC.md、extend.md 继续探索高级用法。【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
