Hardhat v3 与 Vitest 兼容性问题深度解析

问题背景

Hardhat 是一个流行的区块链开发环境，而 Vitest 是一个现代化的前端测试框架。在 Hardhat v3 版本中，开发者发现当尝试将两者结合使用时，会出现无法识别 TypeScript 配置文件的问题。

问题现象

当开发者使用 Vitest 运行测试时，系统会抛出错误："Unknown file extension '.ts' for hardhat.config.ts"。这表明 Vitest 无法正确处理 TypeScript 配置文件。

技术分析

根本原因

问题根源在于 Hardhat v3 的配置文件加载机制。Hardhat 默认会尝试直接加载 .ts 配置文件，这在 Hardhat 自身的测试环境中可以正常工作，因为 Hardhat 内部实现了对 TypeScript 文件的即时编译。然而，当通过 Vitest 运行时，这种即时编译机制没有被触发，导致 Vitest 无法处理 TypeScript 文件的导入。

深层机制

1. 文件加载流程：Hardhat 在启动时会通过 import() 动态加载配置文件
2. 环境差异：Hardhat 测试环境内置了 TypeScript 编译支持，而 Vitest 虽然支持 TypeScript 测试文件，但不支持从依赖项中导入 TypeScript 文件
3. 模块系统：Node.js 原生不支持直接导入 TypeScript 文件，需要额外的转译层

解决方案

临时解决方案

开发者可以通过以下方式临时解决问题：

1. 将 hardhat.config.ts 转换为 JavaScript 文件
2. 确保所有合约都已预先编译（通过 hardhat compile 命令）

长期解决方案

核心开发团队提出了一个更优雅的解决方案：实现一个回退机制，当直接导入 TypeScript 文件失败时，自动尝试使用 tsx 进行转译。具体实现思路如下：

async function importConfigFileWithTsxFallback(configPath) {
    try {
        return await import(configPath);
    } catch (error) {
        if (error.code === "ERR_UNKNOWN_FILE_EXTENSION" && configPath.endsWith(".ts")) {
            const { tsImport }  = await import('tsx/esm/api');
            return tsImport(configPath, import.meta.url)
        }
        throw error;
    }
}

技术启示

1. 工具链兼容性：现代开发工具链日益复杂，不同工具间的兼容性问题需要特别关注
2. 模块加载策略：在开发库或框架时，需要考虑用户可能在不同环境中使用的情况
3. 渐进增强：实现功能时采用渐进式策略，先尝试简单方式，再回退到复杂方案

最佳实践建议

对于需要在 Vitest 中使用 Hardhat 的开发者，建议：

1. 预先编译配置文件为 JavaScript
2. 在测试前确保所有合约都已编译
3. 关注 Hardhat 官方更新，及时获取对 Vitest 的官方支持
4. 考虑在测试设置中添加编译步骤

这个问题展示了现代 JavaScript/TypeScript 生态系统中工具链集成的复杂性，也体现了 Hardhat 团队对开发者体验的重视。通过理解底层机制，开发者可以更好地解决类似问题，并构建更健壮的项目架构。