hardhat-typechain 实战在 Hardhat 中为智能合约自动生成 TypeScript 类型绑定【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhathardhat-typechain 是 Hardhat 官方维护的插件它将 TypeChain 深度集成进编译流水线在合约编译成功后自动生成类型安全的 TypeScript 绑定TypeScript bindings让deploy、test、script中的合约调用获得完整的编译期类型检查。本文以仓库内 packages/hardhat-typechain 的实际源码为准讲解它的安装配置、零配置自动执行机制、全部配置项语义以及底层类型生成原理读完即可在项目中直接落地使用也能看懂它在编译钩子中做了什么。安装与快速接入安装插件插件通过 npm 安装为开发依赖npm install --save-dev nomicfoundation/hardhat-typechain需要注意两点前提该插件依赖nomicfoundation/hardhat-ethers见 src/index.ts 中声明的dependencies因此使用前需先安装并启用 hardhat-ethers 插件如果使用的是官方nomicfoundation/hardhat-toolbox-mocha-ethersEthersMocha Toolbox组合包其中已包含本插件无需再单独安装配置。在 hardhat.config.ts 中启用在hardhat.config.ts中导入插件并加入plugins数组import { defineConfig } from hardhat/config; import hardhatTypechain from nomicfoundation/hardhat-typechain; export default defineConfig({ plugins: [hardhatTypechain], });插件通过definePlugin注册src/index.ts注册时声明了三类 hook 处理器config负责校验并解析typechain用户配置solidity在 Solidity 编译成功后触发类型生成clean在执行 clean 时清理已生成的类型目录。同时它向 CLI 注册了一个全局布尔选项--no-typechain定义于globalOptions用于临时跳过类型生成。零配置自动集成编译即生成README 明确说明使用该插件无需任何额外步骤Hardhat 编译合约时会自动运行它。这一点由solidityhook 保证。在 internal/hook-handlers/solidity.ts 中插件挂接了processArtifactsAfterSuccessfulBuild钩子编译成功后会携带当前项目的root路径、解析后的typechain配置、全局选项noTypechain以及本次构建的全部 artifact 路径调用generateTypes生成类型。也就是说工作流是运行hardhat compile或hardhat test等触发编译的命令编译成功后进入processArtifactsAfterSuccessfulBuildgenerateTypes将所有 artifact 的路径交给 TypeChain 处理生成目录默认出现在项目根目录的types文件夹中。跳过生成的两种方式从 internal/generate-types.ts 可以看到以下任一条件成立时类型生成会被直接跳过配置项dontOverrideCompile: true见下方配置详解命令行传入--no-typechain全局选项。典型的跳过场景是项目已经用 CI 或脚本提前生成过类型或正在调试编译错误、希望加速迭代。配置项详解typechain配置块定义在 src/types.ts通过declare module hardhat/types/config扩充HardhatUserConfigsrc/type-extensions.ts因此可以在hardhat.config.ts中直接书写export default defineConfig({ plugins: [hardhatTypechain], typechain: { outDir: undefined, alwaysGenerateOverloads: false, dontOverrideCompile: false, discriminateTypes: false, tsNocheck: false, }, });各配置项语义如下默认值来自 internal/config/default.ts配置项类型默认值含义outDirstring绝对路径未设置时默认types生成类型文件的输出目录为绝对路径alwaysGenerateOverloadsbooleanfalse是否始终为函数生成完整签名的重载如deposit(uint256)即使该函数没有重载dontOverrideCompilebooleanfalse为true时编译过程中不执行 TypeChaindiscriminateTypesbooleanfalse为重载函数生成基础联合类型而不额外添加帮助 TypeScript 区分具体用例的属性tsNocheckbooleanfalse在生成的类型文件中跳过类型检查相当于在生成文件顶部写入// ts-nocheck配置的解析与校验插件对用户配置的处理分为两阶段见 internal/hook-handlers/config.tsvalidateUserConfig使用 Zod 对typechain配置做结构校验internal/config/validation.ts。outDir必须是字符串并提示「应为存放生成类型的绝对路径」其余四个字段必须是布尔值且整个typechain块允许缺省resolveUserConfig将用户配置与默认配置浅合并...DEFAULT_CONFIG, ...userConfig见 internal/config/get-config.ts得到最终的TypechainConfig挂到解析后的配置对象上。因此即使完全不写typechain块插件也能以全部默认值正常工作——这正是「零配置」的底层保证。底层生成原理generateTypes 做了什么核心实现集中在 internal/generate-types.ts它把编译产物与 TypeChain 衔接起来逻辑可以拆成四个要点。1. 调用 TypeChain固定 ethers-v6 目标插件以编译成功的 artifacts 作为allFiles与filesToProcess以outDir缺省types为输出目录并固定target: ethers-v6——这是当前唯一支持的生成目标。生成选项中还强制node16Modules: true以兼容 ES Modulesenvironment: hardhat用于告知 TypeChain 当前运行环境。路径在传入前会被统一转换为正斜杠格式toForwardSlash以保证 Windows 上反斜杠路径不会破坏 TypeChain 的路径解析。2. 移除 Prettier 输出转换器TypeChain 默认会对生成文件运行 Prettier 格式化这会显著拖慢生成速度且对类型文件收益有限。插件通过修改 TypeChain 输出转换器数组把名为prettierOutputTransformer的转换器移除避免在生成文件上执行 Prettier。3. 注入 compiledFilesTransformer 修正生成代码TypeChain 原生生成的代码与 Hardhat v3 的 TypeScript 编译规则不完全兼容还依赖旧版hardhat-ethers-v2模块。插件注入名为compiledFilesTransformer的输出转换器做三类修正为相对路径的通配导入补上/index.js后缀addJsExtensionsIfNeeded如import type * as src from ./src改写为./src/index.js满足 ESM 解析要求修正模块增强声明将declare module hardhat/types/runtime改写为declare module nomicfoundation/hardhat-ethers/types为合约工厂类注入attach方法addSupportForAttachMethod识别class ContractName__factory extends结构在static connect前插入带类型收窄的override attach(address: string | Addressable)方法并自动补上import type { Addressable } from ethers;。抽象合约的工厂因不继承ContractFactory会被跳过。4. 记录调试信息生成完成后通过createDebug(hardhat:typechain:generate-types)输出Successfully generated N typings!日志可用 Hardhat 的 debug 机制跟踪生成数量。clean 时的自动清理cleanhookinternal/hook-handlers/clean.ts保证生成目录与编译产物同步清理执行hardhat clean时若配置了outDir则删除该目录否则删除项目根目录/typesDEFAULT_OUT_DIR定义于 internal/constants.ts避免残留的陈旧类型文件干扰后续编译。测试用例与边界场景仓库在 test/fixture-projects 下为各种边界场景准备了真实 fixture 工程可作为理解行为的参考generate-types标准的多合约生成场景含A.sol、B.sol验证类型正常产出skip-type-generation配置dontOverrideCompile: true时编译阶段不生成类型其 hardhat.config.ts 是配置跳过的直接示例unified-mode/unified-mode-npmHardhat 统一模式含.t.sol测试合约下类型生成仍正常nothing-to-generate项目无 Solidity 合约仅有占位文件时不报错、优雅跳过compilation-error编译失败的工程不会触发类型生成符合「编译成功后才生成」的钩子语义。这些用例印证了插件「成功即生成、失败即跳过、跳过与清理均受配置约束」的行为边界。小结hardhat-typechain 的价值在于把类型生成从「手动脚本」变成「编译流水线的一环」通过config、solidity、clean三类 hook 完成配置校验解析、编译后自动生成、清理时自动删除outDir、alwaysGenerateOverloads、dontOverrideCompile、discriminateTypes、tsNocheck五个配置项覆盖了输出位置、重载行为、跳过策略与类型检查等全部常用诉求。结合本文对 src/internal/generate-types.ts 的拆解开发者既能在项目中直接启用并自定义也能在遇到生成结果异常时沿着 hook 与输出转换器的调用链快速定位问题。【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
hardhat-typechain 实战在 Hardhat 中为智能合约自动生成 TypeScript 类型绑定【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhathardhat-typechain 是 Hardhat 官方维护的插件它将 TypeChain 深度集成进编译流水线在合约编译成功后自动生成类型安全的 TypeScript 绑定TypeScript bindings让deploy、test、script中的合约调用获得完整的编译期类型检查。本文以仓库内 packages/hardhat-typechain 的实际源码为准讲解它的安装配置、零配置自动执行机制、全部配置项语义以及底层类型生成原理读完即可在项目中直接落地使用也能看懂它在编译钩子中做了什么。安装与快速接入安装插件插件通过 npm 安装为开发依赖npm install --save-dev nomicfoundation/hardhat-typechain需要注意两点前提该插件依赖nomicfoundation/hardhat-ethers见 src/index.ts 中声明的dependencies因此使用前需先安装并启用 hardhat-ethers 插件如果使用的是官方nomicfoundation/hardhat-toolbox-mocha-ethersEthersMocha Toolbox组合包其中已包含本插件无需再单独安装配置。在 hardhat.config.ts 中启用在hardhat.config.ts中导入插件并加入plugins数组import { defineConfig } from hardhat/config; import hardhatTypechain from nomicfoundation/hardhat-typechain; export default defineConfig({ plugins: [hardhatTypechain], });插件通过definePlugin注册src/index.ts注册时声明了三类 hook 处理器config负责校验并解析typechain用户配置solidity在 Solidity 编译成功后触发类型生成clean在执行 clean 时清理已生成的类型目录。同时它向 CLI 注册了一个全局布尔选项--no-typechain定义于globalOptions用于临时跳过类型生成。零配置自动集成编译即生成README 明确说明使用该插件无需任何额外步骤Hardhat 编译合约时会自动运行它。这一点由solidityhook 保证。在 internal/hook-handlers/solidity.ts 中插件挂接了processArtifactsAfterSuccessfulBuild钩子编译成功后会携带当前项目的root路径、解析后的typechain配置、全局选项noTypechain以及本次构建的全部 artifact 路径调用generateTypes生成类型。也就是说工作流是运行hardhat compile或hardhat test等触发编译的命令编译成功后进入processArtifactsAfterSuccessfulBuildgenerateTypes将所有 artifact 的路径交给 TypeChain 处理生成目录默认出现在项目根目录的types文件夹中。跳过生成的两种方式从 internal/generate-types.ts 可以看到以下任一条件成立时类型生成会被直接跳过配置项dontOverrideCompile: true见下方配置详解命令行传入--no-typechain全局选项。典型的跳过场景是项目已经用 CI 或脚本提前生成过类型或正在调试编译错误、希望加速迭代。配置项详解typechain配置块定义在 src/types.ts通过declare module hardhat/types/config扩充HardhatUserConfigsrc/type-extensions.ts因此可以在hardhat.config.ts中直接书写export default defineConfig({ plugins: [hardhatTypechain], typechain: { outDir: undefined, alwaysGenerateOverloads: false, dontOverrideCompile: false, discriminateTypes: false, tsNocheck: false, }, });各配置项语义如下默认值来自 internal/config/default.ts配置项类型默认值含义outDirstring绝对路径未设置时默认types生成类型文件的输出目录为绝对路径alwaysGenerateOverloadsbooleanfalse是否始终为函数生成完整签名的重载如deposit(uint256)即使该函数没有重载dontOverrideCompilebooleanfalse为true时编译过程中不执行 TypeChaindiscriminateTypesbooleanfalse为重载函数生成基础联合类型而不额外添加帮助 TypeScript 区分具体用例的属性tsNocheckbooleanfalse在生成的类型文件中跳过类型检查相当于在生成文件顶部写入// ts-nocheck配置的解析与校验插件对用户配置的处理分为两阶段见 internal/hook-handlers/config.tsvalidateUserConfig使用 Zod 对typechain配置做结构校验internal/config/validation.ts。outDir必须是字符串并提示「应为存放生成类型的绝对路径」其余四个字段必须是布尔值且整个typechain块允许缺省resolveUserConfig将用户配置与默认配置浅合并...DEFAULT_CONFIG, ...userConfig见 internal/config/get-config.ts得到最终的TypechainConfig挂到解析后的配置对象上。因此即使完全不写typechain块插件也能以全部默认值正常工作——这正是「零配置」的底层保证。底层生成原理generateTypes 做了什么核心实现集中在 internal/generate-types.ts它把编译产物与 TypeChain 衔接起来逻辑可以拆成四个要点。1. 调用 TypeChain固定 ethers-v6 目标插件以编译成功的 artifacts 作为allFiles与filesToProcess以outDir缺省types为输出目录并固定target: ethers-v6——这是当前唯一支持的生成目标。生成选项中还强制node16Modules: true以兼容 ES Modulesenvironment: hardhat用于告知 TypeChain 当前运行环境。路径在传入前会被统一转换为正斜杠格式toForwardSlash以保证 Windows 上反斜杠路径不会破坏 TypeChain 的路径解析。2. 移除 Prettier 输出转换器TypeChain 默认会对生成文件运行 Prettier 格式化这会显著拖慢生成速度且对类型文件收益有限。插件通过修改 TypeChain 输出转换器数组把名为prettierOutputTransformer的转换器移除避免在生成文件上执行 Prettier。3. 注入 compiledFilesTransformer 修正生成代码TypeChain 原生生成的代码与 Hardhat v3 的 TypeScript 编译规则不完全兼容还依赖旧版hardhat-ethers-v2模块。插件注入名为compiledFilesTransformer的输出转换器做三类修正为相对路径的通配导入补上/index.js后缀addJsExtensionsIfNeeded如import type * as src from ./src改写为./src/index.js满足 ESM 解析要求修正模块增强声明将declare module hardhat/types/runtime改写为declare module nomicfoundation/hardhat-ethers/types为合约工厂类注入attach方法addSupportForAttachMethod识别class ContractName__factory extends结构在static connect前插入带类型收窄的override attach(address: string | Addressable)方法并自动补上import type { Addressable } from ethers;。抽象合约的工厂因不继承ContractFactory会被跳过。4. 记录调试信息生成完成后通过createDebug(hardhat:typechain:generate-types)输出Successfully generated N typings!日志可用 Hardhat 的 debug 机制跟踪生成数量。clean 时的自动清理cleanhookinternal/hook-handlers/clean.ts保证生成目录与编译产物同步清理执行hardhat clean时若配置了outDir则删除该目录否则删除项目根目录/typesDEFAULT_OUT_DIR定义于 internal/constants.ts避免残留的陈旧类型文件干扰后续编译。测试用例与边界场景仓库在 test/fixture-projects 下为各种边界场景准备了真实 fixture 工程可作为理解行为的参考generate-types标准的多合约生成场景含A.sol、B.sol验证类型正常产出skip-type-generation配置dontOverrideCompile: true时编译阶段不生成类型其 hardhat.config.ts 是配置跳过的直接示例unified-mode/unified-mode-npmHardhat 统一模式含.t.sol测试合约下类型生成仍正常nothing-to-generate项目无 Solidity 合约仅有占位文件时不报错、优雅跳过compilation-error编译失败的工程不会触发类型生成符合「编译成功后才生成」的钩子语义。这些用例印证了插件「成功即生成、失败即跳过、跳过与清理均受配置约束」的行为边界。小结hardhat-typechain 的价值在于把类型生成从「手动脚本」变成「编译流水线的一环」通过config、solidity、clean三类 hook 完成配置校验解析、编译后自动生成、清理时自动删除outDir、alwaysGenerateOverloads、dontOverrideCompile、discriminateTypes、tsNocheck五个配置项覆盖了输出位置、重载行为、跳过策略与类型检查等全部常用诉求。结合本文对 src/internal/generate-types.ts 的拆解开发者既能在项目中直接启用并自定义也能在遇到生成结果异常时沿着 hook 与输出转换器的调用链快速定位问题。【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
