ethers.js 完整指南：TypeScript 编写的 Ethereum 全功能库——特性、安装与 Provider 体系深度解析

区块链Web3【免费下载链接】ethers.jsComplete Ethereum library and wallet implementation in JavaScript.项目地址https://gitcode.com/gh_mirrors/et/ethers.js点击查看免费下载导读ethers.js 是一个用 TypeScript 编写、面向 Ethereum 及其兼容链ilk的完整、紧凑、简洁的 JavaScript 库集成了钱包私钥管理、ABI 合约交互、多网络 Provider 连接与 ENS 域名支持等能力。本文以仓库根目录 README.md 为核心骨架结合 package.json 与 src.ts 下的真实源码实现系统梳理 ethers.js 的定位、核心特性、安装方式、第三方 Provider 协作机制、默认密钥与配额策略以及官方扩展包体系帮助读者在 DApp、钱包与各类工具开发中快速上手并理解其底层工作方式。一、项目定位一个完整、紧凑、简单的 Ethereum 库The Ethers ProjectREADME.md自述为A complete, compact and simple library for Ethereum and ilk, written in TypeScript.这句话定义了项目的三个核心取向Complete完整覆盖 Ethereum 开发所需的大部分核心功能包括钱包、合约、哈希、签名、交易、编码、Provider 等。从 src.ts/ethers.ts 的顶层导出可见库按模块化方式组织为abi、address、constants、contract、crypto、hash、providers、transaction、utils、wallet、wordlists等命名空间并由 package.json 的exports字段提供对应的子路径导入如ethers/abi、ethers/wallet。Compact紧凑README 声称库压缩后约 144kb、未压缩约 460kb见 README.md且以 tree-shaking 为设计目标——打包时只引入实际用到的模块。Simple简单API 设计贴近直觉例如ethers.getDefaultProvider()一条调用即可获得可用 Provider详见下文 Provider 章节。此外项目完全以 TypeScript 编写并启用严格类型检查README.md这在安全性上意义重大私钥、地址、字节串等敏感数据类型在编译期即可获得类型保护。二、核心特性逐条解析附源码佐证README 的Features清单README.md是理解库能力边界的最佳入口下面逐条展开并给出仓库内的实现证据。2.1 私钥留在客户端安全第一的设计Keep your private keys in your client,safeand soundethers.js 的设计哲学是私钥只存在于客户端内存中绝不要求用户把私钥交给服务器或第三方。这在钱包类实现中体现得最彻底——src.ts/wallet 目录下的BaseWallet、HDNodeWallet、VoidSigner等实现均围绕私钥安全展开签名运算在本地通过 src.ts/crypto 中的SigningKey等原语完成私钥不会随 RPC 请求发送到链节点。2.2 JSON 钱包导入导出Geth / Parity / CrowdsaleImport and exportJSON wallets(Geth, Parity and crowdsale)ethers.js 支持三类历史钱包格式的解析与生成Geth / Parity 的 Keystore JSON以 src.ts/wallet/json-keystore.ts 实现提供decryptKeystoreJson、decryptKeystoreJsonSync、encryptKeystoreJson、encryptKeystoreJsonSync等方法均已从 src.ts/ethers.ts 导出。Crowdsale JSON由 src.ts/wallet/json-crowdsale.ts 实现通过isCrowdsaleJson、decryptCrowdsaleJson处理早期的 crowdsale 钱包格式。这些格式在钱包迁移、旧账户恢复场景中非常实用。2.3 BIP-39 助记词与 HD 钱包多语言词表Import and export BIP 39mnemonic phrases(12 word backup phrases) andHD Wallets(English as well as Czech, French, Italian, Japanese, Korean, Simplified Chinese, Spanish, Traditional Chinese)BIP-39 助记词12 个英文单词或按词表语言即可备份整个钱包由 src.ts/wallet/mnemonic.ts 实现。HD 钱包支持层次化确定性派生默认派生路径为m/44/60/0/0/0定义在 src.ts/wallet/hdwallet.tsdefaultPath常量。HD 派生过程基于HMAC-SHA512Bitcoin seed 作为主密钥种子子密钥派生逻辑ser_I也完整位于该文件。多语言词表仓库 src.ts/wordlists 下包含lang-cz捷克语、lang-en英语、lang-fr法语、lang-it意大利语、lang-ja日语、lang-ko韩语、lang-zh简体/繁体中文、lang-es西班牙语、lang-pt葡萄牙语等实现并通过wordlists对象统一导出。2.4 元类Meta-class任意 ABI 生成 JavaScript 对象Meta-classes create JavaScript objects from any contract ABI, includingABIv2andHuman-Readable ABI这是 ethers.js 最具特色的能力之一传入标准 JSON ABI含 ABIv2 的嵌套元组等复杂类型或人类可读 ABIHuman-Readable ABI即直接用function balanceOf(address) view returns (uint256)这样的签名文本即可动态生成合约 JavaScript 对象。底层由 src.ts/abi/interface.tsInterface类和 src.ts/abi/fragments.tsFragment 解析实现Interface.from统一接受 JSON 或人类可读格式。上层由 src.ts/contract 的Contract、ContractFactory承接例如new Contract(address, abi, signerOrProvider)即可获得带类型提示的方法与事件对象。2.5 Provider连接各类节点与第三方服务Connect to Ethereum nodes over JSON-RPC, INFURA, Etherscan, Alchemy, Ankr or MetaMaskethers.js 的 Provider 抽象支持从自建节点到托管服务的多种连接方式JSON-RPC直接连接本地或任意 JSON-RPC 节点如http://localhost:8545由 src.ts/providers/provider-jsonrpc.ts 实现。第三方托管内置 INFURA、Etherscan、Alchemy、Ankr、QuickNode、Cloudflare、Chainstack 等专用 Provider 类位于 src.ts/providers 下provider-infura.ts、provider-etherscan.ts、provider-alchemy.ts、provider-ankr.ts、provider-quicknode.ts、provider-cloudflare.ts、provider-chainstack.ts等。浏览器钱包通过BrowserProvider对接 MetaMask 等 EIP-1193 钱包注入见 src.ts/providers/provider-browser.ts。WebSocketWebSocketProvider支持ws:/wss:端点src.ts/providers/provider-websocket.ts。2.6 ENS 域名一等公民ENS namesare first-class citizens; they can be used anywhere an Ethereum addresses can be used在 ethers.js 中vitalik.eth这样的 ENS 名称与十六进制地址地位等同——凡是接受地址的地方转账目标、合约参数、交易 to 字段等都可以直接传 ENS 名称。底层由 src.ts/providers/ens-resolver.ts 与 src.ts/hash/namehash.tsnamehash、ensNormalize、dnsEncode协作完成名称解析与规范化依赖 package.json 中声明的adraffy/ens-normalize依赖实现 Unicode 规范化。2.7 体积与打包友好Small(~144kb compressed; 460kb uncompressed) /Tree-shakingfocusedREADME 声称压缩后约 144kb、未压缩约 460kbREADME.md这是项目长期坚持紧凑定位的结果。Tree-shaking 方面package.json 显式声明sideEffects: false配合 ESM 构建产物 lib.esmmodule字段指向./lib.esm/index.js使 Rollup、Webpack 等打包器可以按需摇树同时提供 CommonJS 构建产物 lib.commonjsmain字段指向./lib.commonjs/index.js兼顾 Node.js 环境。仓库同时维护了浏览器环境所需的替换入口package.json 的browser字段将 Node 专用的crypto、ws、base64、geturl、ipcsocket、wordlists等实现替换为浏览器版本。2.8 完整功能、文档、测试与开源协议Complete functionality正如 src.ts/ethers.ts 顶层导出所示从AbiCoder、Interface、Contract、Wallet、HDNodeWallet到keccak256、TypedDataEncoder、formatEther、parseUnits、ensNormalize、verifyMessage、verifyTypedData等一应俱全。测试用例README 强调large collection of test cases which are maintained and added toREADME.md。仓库在 src.ts/_tests 维护了覆盖 ABI、地址、合约、密码学、ENS、Provider、RLP、交易、钱包、助记词、词表、单位换算等模块的测试套件同时 testcases 目录存放了abi.json.gz、accounts.json.gz、transaction.json.gz、typed-data.json.gz等大量标准测试向量可用于回归验证与跨实现互操作校验。MIT LicenseREADME 声明协议为 MIT含全部依赖仓库 LICENSE.md 与 package.json 的license: MIT字段一致完全开源可自由使用与再分发。三、安装与引入3.1 Node.js 环境在项目目录执行 npm 安装即可npm install ethers当前仓库 package.json 记录的版本为6.17.0v6 系列且engines字段要求 Node.js 14.0.0package.json。安装后const { ethers } require(ethers); // CommonJSlib.commonjs import { ethers } from ethers; // ESMlib.esm依赖方面运行环境仅需少量精心挑选的依赖见 package.jsonadraffy/ens-normalizeENS 规范化、noble/curves与noble/hashes现代密码学原语、aes-jsAES 加密用于 keystore 钱包、tslib、wsWebSocket 支持等。3.2 浏览器ESM环境README 给出的浏览器引入方式README.mdscript typemodule import { ethers } from ./dist/ethers.min.js; /scriptREADME 说明打包后的库位于仓库./dist/文件夹。需要说明的是当前镜像仓库并未附带构建产物目录若需自行生成可依据 package.json 中的脚本执行npm run build-dist该脚本链会依次完成 TypeScript 编译tsc --project tsconfig.esm.json、Rollup 打包rollup -c配置见 rollup.config.mjs以及 UglifyJS 压缩最终产出ethers.js、ethers.min.js、ethers.umd.js等文件。打包器侧则建议配合sideEffects: false与 ESM 入口获得最佳 tree-shaking 效果。四、Provider 体系从默认 Provider 到自有 API KeyREADME 专门用一节README.md阐述 ethers.js 与第三方 Provider 服务的协作模式这是开发中高频使用的能力下面结合源码深入拆解。4.1 内置社区密钥开箱即用但会被限流ethers.js 与多家第三方服务深度合作在库内内置了各服务的默认 API KeyREADME 称之为 community resources。这意味着// 一行代码即可开始开发 const provider ethers.getDefaultProvider();通过ethers.getDefaultProvider()src.ts/providers/default-provider.ts会创建一个由多家后端组成的 Provider。这些内置密钥是**共享的、刻意限流intentionally throttled**的README.md它们只用于让你快速起步当需要更快响应、更大容量、统计分析或归档数据archival data时应当注册并替换为自己的 API Key。4.2 getDefaultProvider 的分流逻辑从源码 src.ts/providers/default-provider.ts 可以清晰看到其智能分流HTTP(S) URL若network以http:/https:开头直接返回JsonRpcProvider如getDefaultProvider(http://localhost:8545/)。WebSocket若以ws:/wss:开头或传入 WebSocketLike 对象具有send与close方法返回WebSocketProvider。网络名其余情况按网络名mainnet、sepolia、matic等聚合多家第三方后端并组合为FallbackProvider。支持的后端名称backend strings在源码注释与实现中列举为alchemy、ankr、cloudflare、chainstack、etherscan、infura、publicPolygon、quicknode。其中publicPolygon会直接使用 Polygon 公开 RPChttps://polygon-rpc.com/或https://rpc-amoy.polygon.technology/见 src.ts/providers/default-provider.ts。4.3 自定义 API Key 与后端白名单README 提示开发者申请自己的 Provider API Keys而源码进一步说明了如何精确控制后端组合。getDefaultProvider(network, options)的第二个参数options支持// 连接 Polygon只允许 Etherscan 和 INFURA并在 Etherscan 调用中使用自己的密钥 const provider ethers.getDefaultProvider(matic, { etherscan: MY_API_KEY, exclusive: [ etherscan, infura ] });源码规则src.ts/providers/default-provider.ts按名称传入密钥如options.infura、options.etherscan、options.alchemy、options.quicknode、options.ankr等-表示禁用将某后端密钥设为字符串-即可把该后端从默认组合中剔除exclusive白名单可以传单个后端名字符串或后端名字符串数组仅保留名单内的后端INFURA 密钥对象options.infura可以是对象{ projectId, projectSecret }见 src.ts/providers/default-provider.ts应对需要 project secret 的场景。另外注意ankr后端必须有显式密钥才会被启用options.ankr ! null判断这与其它自带社区密钥的后端不同。4.4 Fallback 组合与 quorum 机制当聚合了多家后端时getDefaultProvider会构建FallbackProvidersrc.ts/providers/provider-fallback.ts并采用**法定人数quorum**机制来兼顾可靠性与速度src.ts/providers/default-provider.ts单后端时直接返回该 Provider不额外包装多后端时quorum Math.floor(providers.length / 2)且上限为 2——这是刻意为之公开第三方服务偶有不可靠若要求过高的法定人数会导致请求频繁失败测试网络goerli、kovan、sepolia、classicKotti、optimism-goerli、arbitrum-goerli、matic-mumbai、bnbt等定义于 src.ts/providers/default-provider.ts将 quorum 降为 1因为测试期更看重速度可通过options.quorum手动覆盖该值。4.5 各后端支持的网络范围README 中致谢了 Ankr、QuickNode、Etherscan、INFURA、Alchemy 等服务README.md各专用 Provider 类在网络支持上各有侧重。以 src.ts/providers/provider-infura.ts 为例INFURA 后端支持的网络包括Ethereum 主网mainnet、测试网goerli/sepolia二层网络arbitrum、arbitrum-goerli、arbitrum-sepolia、optimism、optimism-goerli、optimism-sepolia、base、base-goerli、base-sepolia、linea、linea-goerli、linea-sepolia其它链bnb、bnbtBNB 智能链、matic、matic-amoy、matic-mumbaiPolygon 系列。同时该文件顶部定义了内置的默认 Project IDdefaultProjectId见 src.ts/providers/provider-infura.ts——这正是内置密钥、共享限流策略的具体实现之一。五、官方扩展包为 Provider 与工具链补齐能力README 明确指出README.mdethers核心包只包含与 Ethereum 交互最常用、最核心的功能更多增强能力通过独立的官方扩展包提供扩展包作用MulticallProvider一个 Provider将多个call请求合并为单次call降低延迟与后端请求容量消耗MulticoinPluginProvider 插件扩展 ENS 支持的 coin 类型如 BTC、LTC 等地址解析GanacheProvider面向内存节点实例的 Provider用于快速调试、测试与模拟链上操作Optimism UtilitiesOptimism 相关的工具函数集合LedgerSigner直接与 Ledger 硬件钱包交互的 Signer这些扩展包与核心库的插件体系AbstractProviderPlugin、MulticoinProviderPlugin、NetworkPlugin等类型见 src.ts/ethers.ts相配合可以在不污染核心包的前提下按需增强功能。六、文档、动态获取与更新渠道官方文档README 指向完整在线文档其中 Getting Started仓库内亦提供.wrm源文件版本适合零基础快速起步Full API Documentation 则覆盖 src.ts 全模块的 API 细节。仓库 docs.wrm 还包含basics/ABI 基础、cookbook/ENS、签名、React Native 实操、migrating迁移指南等主题文档。重要通知安全公告与重要提醒通过低流量、非营销的官方 Twitter 账号发布并建议 watch 本项目仓库。社区反馈讨论、建议与反馈可通过作者社交账号或社区 Discord 进行。变更日志最新变更记录在仓库根目录 CHANGELOG.md从 README 与 package.json 的版本号6.17.0可以确认当前为 v6 系列。定期摘要项目以接近季度为节奏发布 Highlights 摘要博客README 中列出 2020 年 12 月至 2023 年 8 月的多期适合快速追踪版本演进脉络。七、总结何时选择 ethers.js从 README 的自我定位与源码实现综合来看ethers.js 适合以下场景DApp 前端与浏览器环境体积小、可 tree-shaking、ESM 友好且内置浏览器版密码学与传输实现钱包类应用私钥本地保存、JSON 钱包Geth/Parity/crowdsale、BIP-39 助记词与 HD 钱包、多语言词表一应俱全合约交互Human-Readable ABI 与元类机制大幅降低样板代码配合严格 TypeScript 类型提升开发体验多网络、多 Provider 容灾getDefaultProvider内置多家社区后端并自动构成 Fallback quorum 组合测试网与主网策略自动区分ENS 深度集成域名可作为地址的一等公民直接使用并支持多 coin 类型扩展。在使用内置社区密钥快速起步后建议按 README 的指引尽早注册自有 API Key通过getDefaultProvider(network, options)的exclusive、-与quorum参数定制属于自己的 Provider 组合兼顾成本、性能与可靠性。赞分享区块链Web3【免费下载链接】ethers.jsComplete Ethereum library and wallet implementation in JavaScript.项目地址https://gitcode.com/gh_mirrors/et/ethers.js点击查看免费下载相关推荐Milkdown v7.0新特性10大功能深度解析与完整指南Milkdown v7.0新特性10大功能深度解析与完整指南 Milkdown v7.0 是一次重大版本更新为这个现代化的所见即所得Markdown编辑器带前端富文本插件系统create-vue功能特性深度解析TypeScript、Router、Pinia集成指南create vue功能特性深度解析TypeScript、Router、Pinia集成指南 create vue是官方推荐的Vite驱动Vue项目创建工具为开发工具CLI代码生成前端终极指南sccache分布式编译认证与加密安全特性深度解析终极指南sccache分布式编译认证与加密安全特性深度解析 sccache作为一款高性能的编译缓存工具通过云存储扩展了传统ccache的能力同时在分布式编开发工具构建工具上一篇Amplication billing-types 库深度解析基于 Stigg 的计费特性、套餐与附加服务类型体系下一篇Notepad--终极性能优化指南3个简单技巧让你的编辑器长期流畅运行创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考