本文旨在解决 hardhat 项目中常见的 `referenceerror: api_url_key is not defined` 错误。该错误通常源于 `dotenv` 环境变量加载顺序不当。核心解决方案是确保 `require('dotenv').config();` 语句被放置在 `hardhat.config.js` 文件的最顶部，以保证环境变量在被引用之前成功加载，从而避免配置错误并确保项目正常运行。
理解 ReferenceError: API_URL_KEY is not defined 的根源
在 Hardhat 开发中，为了连接到不同的区块链网络（如 Goerli 测试网），我们通常需要配置 RPC URL 和账户私钥。这些敏感信息不应直接硬编码到代码中，而是通过环境变量进行管理。dotenv 库是 Node.js 项目中一个非常实用的工具，它允许我们从 .env 文件中加载环境变量到 process.env 对象。
当您在 Hardhat 配置中遇到 ReferenceError: API_URL_KEY is not defined 这样的错误时，这明确指出在代码尝试访问 process.env.API_URL_KEY 之前，dotenv 尚未成功加载 .env 文件中的变量。JavaScript 代码是按顺序执行的，如果 require('dotenv').config(); 语句被放置在文件中间，而文件顶部或更早的部分就已经尝试解构或使用 process.env 中的变量，那么这些变量自然会显示为“未定义”。
以下是一个导致该问题的典型 Hardhat 配置示例：
// hardhat.config.js (错误示例)
require("@nomicfoundation/hardhat-toolbox");
/** @type import('hardhat/config').HardhatUserConfig */
module.exports = {
solidity: "0.8.18",
};
/* @type import('hardhat/config').HardhatUserConfig*/
require("@nomiclabs/hardhat-ethers");
// dotenv 在这里才被引入，可能已经晚了
require('dotenv').config();
const { API_URL_KEY, PRIVATE_KEY } = process.env; // 此时 API_URL_KEY 可能尚未定义
module.exports = {
solidity: "0.8.17",
defaultNetwork: "goerli",
networks: {
hardhat: {},
goerli: {
url: API_URL_KEY, // 尝试使用未定义的变量
accounts: [`${PRIVATE_KEY}`]
}
},
};在上述错误示例中，require('dotenv').config(); 被放置在文件的中段。这意味着在 Hardhat 加载其他插件（如 hardhat-toolbox）或在 module.exports 结构体外部直接解构 process.env 变量时，API_URL_KEY 尚未被加载到 process.env 对象中，从而引发 ReferenceError。
解决方案：dotenv 的正确加载时机
解决这个问题的核心在于确保 dotenv 在 Hardhat 配置文件的最顶部被加载。通过将 require('dotenv').config(); 语句放置在文件的开头，我们保证了在文件的任何其他部分（包括 Hardhat 插件的引入和环境变量的解构）尝试访问 process.env 之前，所有的环境变量都已经被正确地从 .env 文件中读取并加载。
以下是修正后的 hardhat.config.js 示例：
// hardhat.config.js (正确示例)
// 确保 dotenv 在所有其他 require 语句和变量访问之前被加载
require('dotenv').config();
// 解构环境变量，此时它们已经可用
const { API_URL_KEY, PRIVATE_KEY } = process.env;
// 引入 Hardhat 插件
require("@nomicfoundation/hardhat-toolbox");
// 如果 hardhat-toolbox 不包含 hardhat-ethers，则需要单独引入
// require("@nomiclabs/hardhat-ethers");
/** @type import('hardhat/config').HardhatUserConfig */
module.exports = {
solidity: "0.8.18", // 根据您的项目需求选择合适的 Solidity 版本
defaultNetwork: "goerli",
networks: {
hardhat: {},
goerli: {
url: API_URL_KEY, // 此时 API_URL_KEY 已经正确加载
accounts: [`${PRIVATE_KEY}`] // 注意是 accounts 数组
}
},
// 示例：其他可选配置，如 gasReporter
// gasReporter: {
// enabled: process.env.REPORT_GAS !== undefined,
// currency: "USD",
// },
};同时，您的 .env 文件应包含所需的变量，例如：
# .env 文件示例 PRIVATE_KEY=b14...3f # 您的私钥，请勿直接公开 API_URL_KEY=https://alien-few-river.ethereum-goerli.discover.quiknode.pro/.../ # 您的 RPC URL
通过以上修改，当 Hardhat 启动并解析 hardhat.config.js 文件时，dotenv 会首先加载环境变量，确保 API_URL_KEY 和 PRIVATE_KEY 在被 Hardhat 配置使用时已经存在于 process.env 中，从而避免 ReferenceError。
注意事项
- .env 文件位置: 确保 .env 文件位于项目的根目录。dotenv 默认会在此位置查找文件。如果 .env 文件位于其他路径，您需要通过 dotenv.config({ path: '/path/to/.env' }); 指定路径。
- 变量命名一致性: .env 文件中的变量名（例如 API_URL_KEY）必须与您在 hardhat.config.js 中通过 process.env 访问的变量名完全匹配。
- Hardhat 插件: Hardhat 的 hardhat-toolbox 插件通常会包含 hardhat-ethers 和其他常用工具。如果您的项目使用了 hardhat-toolbox，则可能不需要单独引入 require("@nomiclabs/hardhat-ethers");。请根据您的 package.json 和实际需求进行调整。
- 配置文件结构: Hardhat 配置文件 (hardhat.config.js) 应该只导出一个配置对象。原始问题中存在两个 module.exports 结构，这是不正确的。所有配置（包括 solidity 版本、networks 等）都应合并到一个 module.exports 对象中。
-
安全实践: 包含敏感信息（如私钥和 API 密钥）的 .env 文件绝不应提交到版本控制系统（如 Git）。请务必将其添加到项目的 .gitignore 文件中，例如：
# .gitignore .env
- accounts 字段: 在 networks 配置中，用于指定账户的字段是 accounts (复数形式，且通常是一个数组)，而不是 account (单数形式)。
总结
ReferenceError: API_URL_KEY is not defined 是一个常见的 Hardhat 配置问题，其根本原因在于 dotenv 环境变量加载的时机不正确。通过将 require('dotenv').config(); 语句放置在 hardhat.config.js 文件的最顶部，可以确保环境变量在被任何代码引用之前成功加载。遵循这一简单的最佳实践，将有助于您构建更健壮、更安全的 Hardhat 项目，并避免因环境变量未定义而导致的运行时错误。正确管理环境变量是任何专业区块链开发项目不可或缺的一部分。
