我想说的是：编写完善、无障碍、流畅的环境搭建指南，只是我的起点。

我相信，任何技术与工具，最终都是为人、为项目、为业务服务的。如果能不依赖图片、不依赖流程图（这些占用文档资源的形式），仅通过文字描述的清晰度和步骤的明确性，就能把技术的复杂度、工具使用的复杂度、版本冲突与不兼容的探索成本，彻底降低——

那么，这种被极致解构并组织得流畅清晰的指引，本身就该成为技术体验的一部分。

它应当让人感受到：技术本可以如此简单、直接、可掌控，就像我们今天使用 AI 工具一样自然。

而我几乎很少见到这样的文档。

每当我写文档时，总是本能地极致细化，只为确保未来再次经历相同场景时，不会踩坑、不会卡壳，甚至希望它能成为“傻瓜式指引”，像吃饭喝水一样顺畅。

也许我的想法有些天真，或过于理想，但我愿意在学习中去做，在实践中调整。不同环境总有难以预测的问题，正因如此，我才更想做这件事——即便它暂时没有经济价值。

📝 说明

这不是一篇技术教程，而是一次坦诚的分享：

为什么我更愿意写文档，而不是只写代码？

希望这段文字能带给你一点力量。

这是我在 Hardhat 官方 GitHub 仓库中回复团队的一段话，原文为英文。我选择保留英文原文，因为它已是公开 Issue 的一部分，且我希望全球开发者都能无障碍阅读。

I'd like to share with you the motivation behind my actions. I'm a developer transitioning from Web2 to Web3, and I want to explain why this shift means so much to me.

While Web2 has evolved over the years with diverse tech stacks and a vast ecosystem, it also carries numerous longstanding issues. In recent times, especially within China, the industry appears to be approaching a stagnation point. When I discovered Web3, I was immediately drawn to its core principles: decentralization, openness, and user sovereignty. These values resonated deeply with me.

One major pain point in Web2 is the lack of proper documentation. Outside of a few top-tier companies, most organizations don’t prioritize maintaining technical documentation. Even when documentation policies exist, the quality is often inconsistent—written reactively to meet internal requirements rather than to support knowledge sharing. Critical information frequently gets lost between development phases, making it difficult to trace decisions or onboard new team members efficiently.

Moreover, most Web2 technologies and codebases are closed-source or only partially open. While this is understandable from a business perspective, it creates significant barriers for developers trying to learn or debug systems. Despite the large developer community, finding accurate, up-to-date, and comprehensive resources can be extremely challenging—let alone accessing knowledge about systems that are entirely proprietary or outdated.

In contrast, Web3 greatly reduces these issues. The transparency of on-chain smart contracts, which anyone can audit, represents a fundamental improvement. When I began learning Web3, my initial goal was to become a smart contract developer. However, as I documented my learning process, I realized I have a stronger passion and aptitude for creating detailed, beginner-friendly technical guides and tutorials.

Currently, the Web3 space lacks in-depth, well-structured documentation. While there are many learning platforms and video tutorials, they often leave learners to navigate numerous pitfalls on their own, consuming significant time and effort. If developers could spend less time troubleshooting tooling issues and instead focus on core aspects—such as business logic, security audits, user experience, gas optimization, and data accuracy (on-chain and off-chain)—it would greatly accelerate the growth and maturity of the Web3 ecosystem.

This insight inspired me to start building a personal Web3 knowledge base and to actively provide feedback to tools and educators I use. My long-term goal is to contribute meaningfully to the Web3 space—ideally securing a role in technical documentation, developer relations, or developer experience. I’ve found that writing documentation gives me far more motivation and fulfillment than coding itself.

For example, I’ve been learning through Patrick Collins’ excellent platform at https://updraft.cyfrin.io/. His courses are clear, high-quality, and very accessible. However, some parts—particularly around tooling setup and environment configuration—have become slightly outdated. I tried reaching out to him via Twitter DM, but couldn’t send a message. I also sent a friend request on Discord, which hasn’t been accepted—likely due to his busy schedule. Eventually, I submitted feedback through his platform, though I’m unsure if he’s seen it.

After that, I decided to file issues directly on the Hardhat GitHub repository, hoping to help other learners who might encounter the same challenges.

Regarding your suggestion about creating a new issue: for now, I don’t think it’s necessary. If I have additional feedback, I’ll organize it into a well-structured document and submit it as a new issue or discussion.

The documentation I’m creating may also serve as a helpful supplement for users navigating your official tools. With clear guidance, learners should be able to get up and running within 30 to 60 minutes, minimizing the need to jump between multiple sources.

As for why I haven’t translated my documents into English yet: I want to ensure accuracy, and I’m not confident that my English proficiency would allow me to properly review or refine machine-translated content. Inaccurate translations could mislead readers, which would defeat the purpose. Even in Chinese, as long as the logic and steps are clearly laid out, English-speaking developers can follow along effectively using translation tools or by tracing the detailed instructions.

版本：v4.8.0最后更新时间：2025年10月3日 目标：规避 hardhat@3.x 的兼容性问题，精准锁定稳定版 v2.26.3，确保在 Node.js v20.18.0 环境下构建无冲突、可部署、可维护的 TypeScript 项目。

• 快速上手-可访问下载此模版项目：

• v2.26.3 hardhat-project-template

• 下载后-先执行：npm run reinstall（安装node_modules）

其他国家可访问：https://rainweb3.github.io/ [web知识库]()

中国内地可访问：\web知识库\

📚 目录（点击跳转）

• 🔧 一、环境准备（Node.js v20.18.0 稳定适配）

  • ✅ 1.1 前提条件

• 🛠 二、初始化项目结构（强制使用 hardhat@2.26.3）

  • ✅ 2.1 创建项目并初始化

  • ✅ 2.2 安装 Hardhat 稳定版本 v2.26.3（关键步骤）

  • 交互式选项详解（逐行说明）

• 📁 三、项目结构演变：从原生生成到完整配置

  • ✅ 3.1 初始生成的项目结构（执行 npx hardhat init 后）

  • ✅ 3.2 完整项目结构（添加所有配置文件后）

  • ✅ 3.3 新增/修改的配置文件说明（对比初始结构）

• ⚙️ 四、修复 Ignition 导入错误与 Solidity 编译器版本不匹配问题

  • 🚫 4.0 hardhat@2.26.3 不支持 Ignition：原因与替代方案详解

  • ✅ 4.1 移除 Ignition 相关代码（hardhat@2.26.3 不支持）

  • ✅ 4.2 修正 hardhat.config.ts 中的 Solidity 编译器版本

  • ✅ 4.3 更新 package.json 脚本（移除 Ignition 相关）

• 🧩 五、依赖版本对齐（精确锁定，避免 3.x 升级）

  • ✅ 5.1 清理并替换 package.json

  • ✅ 5.2 使用更新后的 package.json（项目名已更改为 hardhat-project）

  • ✅ 5.3 安装最终依赖

• ⚙️ 六、新增与修改的配置文件详解

  • ✅ 6.1 .prettierrc（新增）

  • ✅ 6.2 eslint.config.js（新增）

  • ✅ 6.3 .editorconfig（新增）

  • ✅ 6.4 .env（新增）

  • ✅ 6.5 .gitignore（增强）

  • ✅ 6.6 .vscode/settings.json（增强）

• ⚠️ 七、修复 VS Code TypeScript 编译器错误（tsconfig.json 问题）

  • 🚫 7.0 问题描述

  • 🔍 7.1 根本原因分析

  • ✅ 7.2 推荐解决方案（无需修改源码）

  • ✅ 7.3 替代方案（修改 tsconfig.json，不推荐）

• 🧪 八、验证环境（确保 v2.26.3 正常工作）

  • ✅ 8.1 编译合约

  • ✅ 8.2 运行测试

  • ✅ 8.3 启动本地节点

  • ✅ 8.4 部署测试

• 📦 九、智能合约开发常用命令汇总（含 ts-node 执行）

• ⚠️ 十、安全审计问题说明与处理建议

• ✅ 十一、结论 -\📄 Hardhat 单文件编译指南\ -\📚 Hardhat 项目中 ESLint & Prettier 集成问题全记录\

🔧 一、环境准备（Node.js v20.18.0 稳定适配）

✅ 1.1 前提条件

• Node.js：v20.18.0（LTS，推荐）

• npm：v10.8.2（随 Node.js v20 安装）

• Git（可选）

• 文本编辑器：推荐使用 VS Code

⚠️ 重要提醒：hardhat@3.x 版本（如 3.0.4）为早期主版本，存在 API 变更、插件不兼容、文档缺失等问题，不建议在生产或学习项目中使用。

# 检查版本
node -v  # 预期输出：v20.18.0
npm -v   # 预期输出：10.8.2

💡 若版本不符，请使用 nvm 切换：

# 安装 nvm（Linux/macOS）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重启终端后
nvm install 20.18.0
nvm use 20.18.0
nvm alias default 20.18.0

🛠 二、初始化项目结构（强制使用 hardhat@2.26.3）

✅ 2.1 创建项目并初始化

mkdir hardhat-project
cd hardhat-project
npm init -y

✅ 2.2 安装 Hardhat 稳定版本 v2.26.3（关键步骤）

⚠️ 切勿使用 npm install --save-dev hardhat，否则会安装最新的 3.0.4，该版本存在严重兼容性问题。

npm install --save-dev hardhat@2.26.3
npx hardhat init

交互式选项详解（逐行说明）：

? What do you want to do? 
  Create a JavaScript project
> Create a TypeScript project
  Create a TypeScript project (with Viem)
  Create an empty hardhat.config.js
  Quit

✅ 选择：Create a TypeScript project

原因：本人的配置使用 ethers 而非 viem，选择此项将生成基于 ethers 和 chai 的标准 TypeScript 项目结构。

? Hardhat project root: /your/path/hardhat-project

✅ 回车确认默认路径。

? Do you want to add a .gitignore? (Y/n)

✅ 输入 Y，自动创建 .gitignore。

? Do you want to install this sample project's dependencies with npm (@nomicfoundation/hardhat-toolbox)? (Y/n) »

✅ 输入 y

选项说明：

• 此选项询问是否自动安装 @nomicfoundation/hardhat-toolbox 及其依赖（如 eslint, prettier, typescript, chai, ethers 等）。

• ✅ 选择 y：自动安装推荐的开发依赖，节省手动配置时间，且版本与 hardhat@2.26.3 兼容。

• ❌ 选择 n：需手动安装所有依赖，容易出错且耗时。

• 注意：即使选择 y，后续仍需用本人提供的 package.json 替换以锁定精确版本。

⚠️ 关于安装过程中的警告说明

执行 npm install 时可能出现：

npm warn deprecated glob@8.1.0: Glob versions prior to v9 are no longer supported
npm warn deprecated eslint@8.57.1: This version is no longer supported...

结论：这些是非阻塞性警告，源于 hardhat-toolbox 对旧版 eslint 的依赖。hardhat@2.26.3 + toolbox@^4.0.0 + eslint@^8.57.0 是当前最稳定的组合，无需修复。

📁 三、项目结构演变：从原生生成到完整配置

本节清晰区分 初始生成结构 与 最终完整结构，并说明新增/修改项。

✅ 3.1 初始生成的项目结构（执行 npx hardhat init 后）

执行 npx hardhat init 并选择 Create a TypeScript project 后，Hardhat 自动生成的项目结构如下：

hardhat-project/
├── contracts/                 # 存放 Solidity 智能合约源代码（.sol 文件）
│   └── Lock.sol               # 示例合约：带时间锁的转账合约
├── scripts/                   # 存放自定义部署或交互脚本（.ts 文件）
│   └── deploy.ts              # 示例：部署合约到指定网络的脚本
├── test/                      # 存放合约测试用例（.ts 文件）
│   └── Lock.ts                # 示例：对 Lock 合约进行单元测试
├── node_modules/              # npm 安装的所有依赖包（自动生成）
├── .gitignore                 # Git 忽略文件规则（已包含基础规则）
├── hardhat.config.ts          # Hardhat 主配置文件（网络、Solidity 版本等）
├── package-lock.json          # npm 依赖锁定文件（自动生成）
├── package.json               # 项目元信息与依赖声明
├── README.md                  # 项目说明文档
└── tsconfig.json              # TypeScript 编译配置

⚠️ 此时缺少：.prettierrc, eslint.config.js, .editorconfig, .env, .vscode/settings.json 等高级配置文件。

✅ 3.2 完整项目结构（添加所有配置文件后）

在添加所有配置文件和环境变量后，最终的项目结构如下：

hardhat-project/
├── contracts/                 # 存放 Solidity 智能合约源代码（.sol 文件）
│   └── Lock.sol               # 示例合约：带时间锁的转账合约
├── scripts/                   # 存放自定义部署或交互脚本（.ts 文件）
│   └── deploy.ts              # 示例：部署合约到指定网络的脚本
├── test/                      # 存放合约测试用例（.ts 文件）
│   └── Lock.ts                # 示例：对 Lock 合约进行单元测试
├── node_modules/              # npm 安装的所有依赖包（自动生成）
├── .vscode/                   # VS Code 编辑器配置
│   └── settings.json          # 编辑器格式化、保存等行为配置
├── .env                       # 环境变量文件（本地开发使用，不应提交到 Git）
├── .env.local                 # 本地环境变量覆盖文件（Git 忽略）
├── encryptedKey.json          # 加密的私钥文件（Git 忽略）
├── .editorconfig              # 统一编辑器缩进、换行等风格
├── .eslint.config.js          # ESLint 代码规范检查配置
├── .gitignore                 # Git 忽略文件规则
├── .prettierrc                # Prettier 代码格式化配置
├── hardhat.config.ts          # Hardhat 主配置文件（网络、Solidity 版本等）
├── package-lock.json          # npm 依赖锁定文件（自动生成）
├── package.json               # 项目元信息与依赖声明
├── README.md                  # 项目说明文档
└── tsconfig.json              # TypeScript 编译配置

✅ 变化说明：

• 已移除 ignition/ 目录，因为 hardhat@2.26.3 不支持 hardhat-ignition。

• 新增 .vscode/, .prettierrc, .eslint.config.js, .editorconfig, .env 等配置文件。

• .gitignore 内容被增强，以忽略更多文件。

✅ 3.3 新增/修改的配置文件说明（对比初始结构）

| 文件/目录 | 类型 | 作用说明 |

|----------|------|----------|

| .prettierrc | 新增 | Prettier 格式化配置，统一代码风格 |

| eslint.config.js | 新增 | ESLint 代码规范检查配置，集成 Prettier，确保代码质量 |

| .editorconfig | 新增 | 统一不同编辑器的缩进、换行等基础风格 |

| .env | 新增 | 存放私钥、RPC URL 等敏感环境变量 |

| .env.local | 新增 | 本地环境变量覆盖，优先级高于 .env |

| encryptedKey.json | 新增 | 存放加密后的私钥文件 |

| .vscode/settings.json | 新增 | VS Code 编辑器行为配置，实现保存时自动格式化与修复 |

| .gitignore | 修改 | 在初始基础上增强，新增忽略 dist/, cache/, coverage/, encryptedKey.json, .env.* 等 |

⚙️ 四、修复 Ignition 导入错误与 Solidity 编译器版本不匹配问题

🛠 问题描述：

1. import { buildModule } from "@nomicfoundation/hardhat-ignition/modules"; 报错：找不到模块。

2. npx hardhat compile 报错：Error HH606: The project cannot be compiled，Solidity 版本 ^0.8.28 与配置不匹配。

根本原因：

• hardhat@2.26.3 不支持 hardhat-ignition，该功能是 hardhat@3.x 的实验性功能。

• hardhat-toolbox 默认配置的 Solidity 编译器版本可能不包含 0.8.28。

🚫 4.0 hardhat@2.26.3 不支持 Ignition：原因与替代方案详解

⚠️ 核心原因说明：

@nomicfoundation/hardhat-ignition 是 Hardhat 团队为 Hardhat v3.x 系列开发的全新、实验性的模块化部署系统。它旨在简化复杂合约系统的部署流程，提供更强大的依赖管理和部署状态追踪能力。

hardhat@2.26.3（属于 v2.x 系列）发布于 Hardhat Ignition 功能之前，其代码库中完全不包含 hardhat-ignition 模块。 因此，尝试在 v2.26.3 项目中导入 @nomicfoundation/hardhat-ignition/modules 会直接导致模块解析失败，报错：

Error: Cannot find module '@nomicfoundation/hardhat-ignition/modules'

这不是配置错误，而是版本不兼容的必然结果。

📌 重要提示：即使本人手动通过 npm install @nomicfoundation/hardhat-ignition 安装该插件，它也无法在 v2.26.3 上正常工作，因为其底层依赖和 API 与 v2.x 不兼容。

✅ 替代方案与操作步骤

由于 hardhat@2.26.3 不支持 Ignition，必须使用 传统的部署方式，即通过 Hardhat Runtime Environment (HRE) 中的 ethers 插件来手动部署合约。

替代方案：使用 ethers.deployContract()

这是 Hardhat v2.x 的标准部署方法，稳定、可靠、文档完善。

操作步骤如下：

1. 删除 ignition/ 目录（如果存在）：

   rm -rf ignition
   

2. 修改或创建部署脚本（如 scripts/deploy.ts），使用 ethers.deployContract 代替 buildModule：

   import { ethers } from "hardhat";
   
   async function main() {
     // 部署 Lock 合约，构造函数参数为解锁时间戳
     const unlockTime = Math.floor(Date.now() / 1000) + 60; // 60秒后解锁
     const lockedAmount = ethers.parseEther("1"); // 锁定1 ETH
   
     const lock = await ethers.deployContract("Lock", [unlockTime], {
       value: lockedAmount
     });
   
     await lock.waitForDeployment();
     console.log(`Lock contract deployed to ${lock.target}`);
   }
   
   main()
     .then(() => process.exit(0))
     .catch((error) => {
       console.error(error);
       process.exit(1);
     });
   

   ✅ 说明：

   • ethers.deployContract("Lock", [unlockTime], { value: lockedAmount })：直接部署合约，传入构造函数参数和交易选项（如 value）。

   • await lock.waitForDeployment()：等待部署交易上链并确认。

   • lock.target：获取部署后的合约地址。

3. 无需修改 hardhat.config.ts 来支持此方案，ethers 插件已由 @nomicfoundation/hardhat-toolbox 自动加载。

4. 更新 package.json 脚本，移除 deploy:ignition 等相关命令，仅保留基于 scripts/ 的部署命令。

✅ 4.1 移除 Ignition 相关代码（hardhat@2.26.3 不支持）

（此节为 4.0 节的实践总结）

1. 删除 ignition/ 目录（如果存在）：

   rm -rf ignition
   

2. 修改 scripts/deploy.ts（如果引用了 buildModule）：

   import { ethers } from "hardhat";
   
   async function main() {
     const lock = await ethers.deployContract("Lock", [Date.now() + 1000]);
     await lock.waitForDeployment();
     console.log(`Lock deployed to ${lock.target}`);
   }
   
   main().catch((error) => {
     console.error(error);
     process.exitCode = 1;
   });
   

   ✅ 说明：使用 ethers.deployContract 代替 buildModule，这是 hardhat@2.x 的标准部署方式。

✅ 4.2 修正 hardhat.config.ts 中的 Solidity 编译器版本

确保 hardhat.config.ts 中的 solidity 配置包含 0.8.28：

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";

const config: HardhatUserConfig = {
  solidity: {
    version: "0.8.28",
    settings: {
      optimizer: {
        enabled: true,
        runs: 200,
      },
    },
  },
  networks: {
    hardhat: {
      chainId: 1337,
    },
  },
  paths: {
    sources: "./contracts",
    tests: "./test",
    cache: "./cache",
    artifacts: "./artifacts"
  },
  mocha: {
    timeout: 40000
  }
};

export default config;

✅ 关键点：

• 明确设置 version: "0.8.28"，与 Lock.sol 中的 pragma solidity ^0.8.28; 匹配。

• hardhat-toolbox 支持 0.8.28，无需额外安装编译器。

✅ 4.3 更新 package.json 脚本（移除 Ignition 相关）

确保 package.json 中的脚本不包含 ignition 相关命令：

"scripts": {
  "ts-node": "npx ts-node",
  "build": "tsc",
  "compile": "hardhat compile",
  "test": "hardhat test",
  "node": "hardhat node",
  "deploy:local": "hardhat run scripts/deploy.ts --network localhost",
  "deploy:sepolia": "hardhat run scripts/deploy.ts --network sepolia",
  "clean": "npx rimraf node_modules package-lock.json dist artifacts cache coverage types",
  "outdated": "npm outdated",
  "format": "prettier --plugin prettier-plugin-solidity --write \"**/*.{js,cjs,ts,sol}\"",
  "format:check": "prettier --plugin prettier-plugin-solidity --check \"**/*.{js,cjs,ts,sol}\"",
  "lint": "eslint \"**/*.{ts,js,sol}\" --ext .ts,.js",
  "lint:fix": "eslint \"**/*.{ts,js,sol}\" --ext .ts,.js --fix",
  "reinstall": "npm run clean && npm install"
}

✅ 说明：已移除 deploy:ignition 等不适用于 hardhat@2.26.3 的脚本。

🧩 五、依赖版本对齐（精确锁定，避免 3.x 升级）

✅ 5.1 清理并替换 package.json

rm -rf node_modules package-lock.json

✅ 5.2 使用更新后的 package.json（项目名已更改为 hardhat-project）

{
  "name": "hardhat-project",
  "version": "1.0.0",
  "main": "hardhat.config.js",
  "scripts": {
    "ts-node": "npx ts-node",
    "build": "tsc",
    "compile": "hardhat compile",
    "test": "hardhat test",
    "node": "hardhat node",
    "deploy:local": "hardhat run scripts/deploy.ts --network localhost",
    "deploy:sepolia": "hardhat run scripts/deploy.ts --network sepolia",
    "clean": "npx rimraf node_modules package-lock.json dist artifacts cache coverage types",
    "outdated": "npm outdated",
    "format": "prettier --plugin prettier-plugin-solidity --write \"**/*.{js,cjs,ts,sol}\"",
    "format:check": "prettier --plugin prettier-plugin-solidity --check \"**/*.{js,cjs,ts,sol}\"",
    "lint": "eslint \"**/*.{ts,js,sol}\" --ext .ts,.js",
    "lint:fix": "eslint \"**/*.{ts,js,sol}\" --ext .ts,.js --fix",
    "reinstall": "npm run clean && npm install"
  },
  "devDependencies": {
    "@nomicfoundation/hardhat-toolbox": "^4.0.0",
    "@types/chai": "^4.3.10",
    "@types/fs-extra": "^11.0.4",
    "@types/glob": "^8.1.0",
    "@types/minimatch": "^5.1.2",
    "@types/node": "^20.19.13",
    "@typescript-eslint/eslint-plugin": "^6.21.0",
    "@typescript-eslint/parser": "^6.21.0",
    "chai": "^4.3.10",
    "dotenv": "^16.4.5",
    "eslint": "^8.57.0",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.1.3",
    "ethers": "^6.15.0",
    "forge-std": "github:foundry-rs/forge-std#v1.9.4",
    "hardhat": "^2.26.3",
    "minimatch": "^9.0.3",
    "prettier": "^3.2.5",
    "prettier-plugin-solidity": "^1.1.3",
    "ts-node": "^10.9.2",
    "typescript": "~5.8.3"
  },
  "overrides": {
    "globby": {
      "@types/glob": "$@types/glob"
    },
    "minimatch": {
      "@types/minimatch": "5.1.2"
    }
  },
  "dependencies": {
    "crypto-js": "^4.2.0"
  },
  "description": "This project showcases a Hardhat 3 Beta project using `mocha` for tests and the `ethers` library for Ethereum interactions.",
  "directories": {
    "test": "test"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

✅ 关键点：

• "name": "hardhat-project"：项目名称已按要求更新。

• "hardhat": "^2.26.3"：明确锁定 2.x 分支，避免意外升级到 3.x。

• "@nomicfoundation/hardhat-toolbox": "^4.0.0"：与 hardhat@2.26.3 完全兼容。

• "eslint": "^8.57.0"：toolbox 所需，不可升级至 v9。

✅ 5.3 安装最终依赖

⚠️ 安装后可能出现 13 low severity vulnerabilities，请参见下方 十、安全审计问题说明与处理建议。

⚙️ 六、新增与修改的配置文件详解

✅ 6.1 .prettierrc（新增）

{
  "semi": false,
  "singleQuote": false,
  "printWidth": 80,
  "tabWidth": 4,
  "useTabs": false,
  "endOfLine": "lf",
  "arrowParens": "avoid",
  "plugins": ["prettier-plugin-solidity"]
}

作用：定义代码格式化规则。

• semi: false：不使用分号结尾。

• singleQuote: false：使用双引号。

• printWidth: 80：每行最大 80 字符。

• tabWidth: 4：缩进 4 空格。

• useTabs: false：使用空格缩进。

• endOfLine: "lf"：使用 LF 换行符（Unix 风格）。

• arrowParens: "avoid"：箭头函数参数为单个时省略括号。

• plugins: ["prettier-plugin-solidity"]：支持 Solidity 格式化。

✅ 6.2 eslint.config.js（新增）

module.exports = {
  env: {
    es2021: true,
    node: true,
  },
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: 12,
    sourceType: "module"
  },
  plugins: ["@typescript-eslint", "prettier"],
  rules: {
    "prettier/prettier": "error",
    "no-console": "off",
    "no-debugger": "warn"
  },
  ignorePatterns: ["node_modules/", "dist/"]
};

作用：ESLint 代码检查配置。

• 继承 eslint:recommended 和 @typescript-eslint/recommended。

• 集成 prettier，冲突时以 Prettier 为准。

• prettier/prettier: "error"：格式错误视为 ESLint 错误。

• no-console: "off"：允许使用 console.log。

• no-debugger: "warn"：调试器语句仅警告。

• ignorePatterns：忽略 node_modules/ 和 dist/ 目录。

✅ 6.3 .editorconfig（新增）

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 4
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.sol]
indent_size = 4

[*.md]
trim_trailing_whitespace = false

作用：统一不同编辑器的基础风格。

• [*]：所有文件使用 UTF-8、4 空格缩进、LF 换行。

• [*.sol]：Solidity 文件缩进为 4 空格。

• [*.md]：Markdown 文件允许行尾空格。

✅ 6.4 .env（新增）

REMOTE_TEST_PRIVATE_KEY="私钥"
REMOTE_TEST_RPC_URL="测试网地址"
ENCRYPTION_PASSWORD="加密密码"

作用：存储敏感环境变量，不应提交到 Git。

✅ 6.5 .gitignore（增强）

# Node modules
/node_modules

# Compilation output
/dist

# Hardhat Build Artifacts
/artifacts
/cache
/coverage
/types

# IDE & Editor
.vscode/*
!.vscode/settings.json

# Environment
.env
encryptedKey.json
.env.local

# Logs
*.log

# Prettier & ESLint cache
.node_modules
.cache
eslint-cache

# OS
.DS_Store
Thumbs.db

作用：在初始 .gitignore 基础上增强，新增忽略 dist/, cache/, coverage/, encryptedKey.json, .env.* 等敏感或构建产物。

✅ 6.6 .vscode/settings.json（增强）

{
    "editor.tabSize": 4,
    "editor.detectIndentation": false,
    "editor.insertSpaces": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": "explicit"
    },
    "files.autoSave": "onFocusChange",
    "files.eol": "\n",
    "typescript.validate.enable": true,
    "javascript.validate.enable": false
}

作用：配置 VS Code 实现保存时自动格式化（Prettier）和修复（ESLint）。

⚠️ 七、修复 VS Code TypeScript 编译器错误（tsconfig.json 问题）

🚫 7.0 问题描述

在 VS Code 中打开项目时，node_modules/@nomicfoundation/hardhat-toolbox/src/tsconfig.json 文件出现以下 TypeScript 编译错误：

无法读取文件“.../node_modules/config/typescript/tsconfig.json”。
Parent configuration missing
找不到文件“.../node_modules/@nomicfoundation/hardhat-core/src”。
找不到文件“.../node_modules/@nomicfoundation/hardhat-chai-matchers”。
找不到文件“.../node_modules/@nomicfoundation/hardhat-ethers/src”。
...

这些错误虽然不影响项目编译、测试和部署的实际运行，但会在 VS Code 的“问题”面板中显示，可能干扰开发体验。

🔍 7.1 根本原因分析

这些错误源于 @nomicfoundation/hardhat-toolbox 包内部的 tsconfig.json 文件配置：

{
  "extends": "../config/typescript/tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "outDir": "../../dist"
  },
  "references": [
    { "path": "../hardhat-core/src" },
    { "path": "../hardhat-chai-matchers" },
    { "path": "../hardhat-network-helpers" },
    { "path": "../hardhat-ethers/src" },
    { "path": "../hardhat-waffle/src" }
  ]
}

问题本质：

1. extends 路径错误：../config/typescript/tsconfig.json 不存在于 node_modules 中。该路径是 Hardhat 团队在源码仓库中使用的，用于构建流程。

2. references 路径失效："../hardhat-core/src" 等路径在 node_modules 中无法解析，因为 hardhat-core 等包的源码（src/ 目录）不会被发布到 npm。npm 发布的是编译后的 dist/ 文件。

3. 开发构建配置：此 tsconfig.json 是 hardhat-toolbox 项目在开发和构建阶段使用的配置，用于将 toolbox 与 core、ethers 等插件组合编译。一旦发布，此配置对使用者已无实际意义。

✅ 结论：这些错误是无害的。VS Code 的 TypeScript 语言服务试图解析所有可见的 tsconfig.json 文件，但 node_modules 中的此类配置文件不应被主项目继承或使用。

#✅ 7.2 推荐解决方案（无需修改源码）

最安全、最推荐的做法是：让 VS Code 忽略 node_modules 中的 tsconfig.json 文件。

✅ 方法一：修改 VS Code 设置（全局或工作区）

在 VS Code 的设置中添加以下配置，阻止其扫描 node_modules 目录下的 tsconfig.json 文件：

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enableTsServerTrace": false,
  "typescript.preferences.includePackageJsonAutoImports": "auto",
  "typescript.suggest.autoImports": true,
  "typescript.validate.enable": true,
  "javascript.validate.enable": true,
  "typescript.tsc.autoDetect": "on",
  "typescript.preferences.renameShorthandProperties": true,
  "typescript.suggest.enabled": true,
  "typescript.updateImportsOnFileMove.enabled": "prompt",
  "typescript.preferences.includeInlayParameterNameHints": "literals",
  "typescript.inlayHints.parameterNames.enabled": false,
  "typescript.inlayHints.variableTypes.enabled": false,
  "typescript.inlayHints.propertyDeclarationTypes.enabled": false,
  "typescript.inlayHints.functionLikeReturnTypes.enabled": false,
  "typescript.inlayHints.enumMemberValues.enabled": false,
  "typescript.preferences.quoteStyle": "auto",
  "typescript.suggest.completeJSDocs": true,
  "typescript.suggest.autoImportSuggestionsMode": "recentlyUsed",
  "typescript.suggest.showModuleSuggestions": true,
  "typescript.suggest.showClassSuggestions": true,
  "typescript.suggest.showInterfaceSuggestions": true,
  "typescript.suggest.showConstructorSuggestions": true,
  "typescript.suggest.showModuleSuggestions": true,
  "typescript.suggest.showVariableSuggestions": true,
  "typescript.suggest.showPropertySuggestions": true,
  "typescript.suggest.showFunctionSuggestions": true,
  "typescript.suggest.showMethodSuggestions": true,
  "typescript.suggest.showEventSuggestions": true,
  "typescript.suggest.showOperatorSuggestions": true,
  "typescript.suggest.showKeywordSuggestions": true,
  "typescript.suggest.showSnippetSuggestions": true,
  "typescript.suggest.showPathSuggestions": true,
  "typescript.suggest.showDeprecatedItems": true,
  "typescript.suggest.autoImports": true,
  "typescript.suggest.names": true,
  "typescript.suggest.paths": true,
  "typescript.suggest.packageJson": true,
  "typescript.suggest.importModuleSpecifier": "auto",
  "typescript.suggest.importModuleSpecifierEnding": "auto",
  "typescript.suggest.includeCompletionsForImportStatements": true,
  "typescript.suggest.includeCompletionsForModuleExports": true,
  "typescript.suggest.includeCompletionsWithInsertText": true,
  "typescript.suggest.includeCompletionsWithSnippetText": true,
  "typescript.suggest.filterSuggestions": true,
  "typescript.suggest.autoImports": true,
  "typescript.preferences.includePackageJsonAutoImports": "auto"
}

更关键的是，确保 VS Code 不加载 node_modules 中的配置文件。可在工作区 .vscode/settings.json 中添加：

{
  "typescript.preferences.disableSuggestions": false,
  "typescript.suggest.enabled": true,
  "typescript.validate.enable": true,
  "typescript.tsc.autoDetect": "on",
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.disableAutomaticTypeAcquisition": false,
  "typescript.suggest.autoImports": true,
  "typescript.suggest.includeCompletionsForImportStatements": true,
  "typescript.suggest.includeCompletionsWithSnippetText": true,
  "typescript.suggest.filterSuggestions": true,
  "typescript.suggest.autoImports": true,
  "typescript.preferences.includePackageJsonAutoImports": "auto",
  "typescript.preferences.quoteStyle": "auto",
  "typescript.preferences.renameShorthandProperties": true,
  "typescript.preferences.includeInlayParameterNameHints": "none",
  "typescript.inlayHints.parameterNames.enabled": false,
  "typescript.inlayHints.variableTypes.enabled": false,
  "typescript.inlayHints.propertyDeclarationTypes.enabled": false,
  "typescript.inlayHints.functionLikeReturnTypes.enabled": false,
  "typescript.inlayHints.enumMemberValues.enabled": false,
  "typescript.updateImportsOnFileMove.enabled": "prompt",
  "typescript.suggest.completeJSDocs": true,
  "typescript.suggest.autoImportSuggestionsMode": "all",
  "typescript.suggest.showModuleSuggestions": true,
  "typescript.suggest.names": true,
  "typescript.suggest.paths": true,
  "typescript.suggest.packageJson": true,
  "typescript.suggest.importModuleSpecifier": "auto",
  "typescript.suggest.importModuleSpecifierEnding": "auto",
  "typescript.preferences.disableAutomaticTypeAcquisition": false
}

或者，直接通过 VS Code 图形界面操作：

1. 打开命令面板（Ctrl+Shift+P）

2. 输入并选择 “Preferences: Open Settings (JSON)”

3. 在打开的 settings.json 文件中添加：

{
  "typescript.preferences.disableSuggestions": false,
  "typescript.suggest.enabled": true,
  "typescript.validate.enable": true,
  "typescript.tsc.autoDetect": "on",
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.disableAutomaticTypeAcquisition": false,
  "typescript.suggest.autoImports": true
}

这样配置后，VS Code 将优先使用项目根目录的 tsconfig.json，并忽略 node_modules 中可能干扰的配置文件，从根本上避免类型冲突问题。

简化并提供正确方案如下：

✅ 7.2 推荐解决方案（无需修改源码）

最安全、最推荐的做法是：让 VS Code 忽略 node_modules 中的 tsconfig.json 文件。

✅ 方法一：修改 VS Code 设置（工作区级）

在项目根目录的 .vscode/settings.json 中添加：

{
  "typescript.validate.enable": true,
  "typescript.validate.disableDeepValidation": true,
  "typescript.suggest.autoImports": false,
  "typescript.preferences.includePackageJsonAutoImports": "off",
  "typescript.tsserver.experimental.enableProjectDiagnostics": false
}

说明：

• "typescript.validate.disableDeepValidation": true：禁用对 node_modules 的深度类型验证，可显著减少错误提示。

• 其他设置用于优化 TypeScript 语言服务性能。

✅ 方法二：使用 tsconfig.json 排除（项目级）

在项目根目录的 tsconfig.json 中添加 exclude 字段：

{
  "compilerOptions": {
    // ... 你的现有配置
  },
  "exclude": [
    "node_modules"
  ]
}

说明：明确告诉 TypeScript 编译器忽略 node_modules 目录。虽然语言服务可能仍会索引，但可减少错误。

✅ 方法三：关闭 node_modules 的 TS 验证（VS Code 设置）

在 VS Code 的 settings.json 中：

{
  "typescript.validate.enable": false
}

⚠️ 警告：此方法会完全关闭 TypeScript 验证，不推荐。

✅ 7.3 替代方案（修改 tsconfig.json，不推荐）

仅当上述方法无效且错误严重影响开发时考虑。

1. 定位文件：

   # Windows
   notepad "node_modules/@nomicfoundation/hardhat-toolbox/src/tsconfig.json"
   

2. 修改为：

   {
     "compilerOptions": {
       "outDir": "../../dist"
     }
   }
   

3. 保存后重启 VS Code。

❌ 为什么不推荐：

• 修改 node_modules 是临时且危险的。

• npm install 会覆盖修改。

• 可能破坏包的构建信息。

🧪 八、验证环境（确保 v2.26.3 正常工作）

✅ 8.1 编译合约

npx hardhat compile

✅ 输出：Compiled 1 Solidity file successfully

✅ 8.2 运行测试

npx hardhat test

✅ 输出：1 passing

✅ 8.3 启动本地节点

✅ 输出：Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/

✅ 8.4 部署测试

npx hardhat run scripts/deploy.ts --network localhost

✅ 输出：Lock with 1 ETH and unlock timestamp ... deployed to ...

📦 九、智能合约开发常用命令汇总（含 ts-node 执行）

| 命令 | 说明 |

|------|------|

| npx hardhat compile | 编译 Solidity 合约 |

| npx hardhat test | 运行测试用例 |

| npx hardhat node | 启动本地 Hardhat 节点（本地测试网） |

| npx hardhat run scripts/deploy.ts --network localhost | 部署合约到本地节点 |

| npx hardhat run scripts/deploy.ts --network sepolia | 部署合约到 Sepolia 测试网 |

| npm run format | 格式化代码（通常使用 Prettier） |

| npm run lint | 检查代码规范（通常使用 ESLint） |

| npm run clean | 清理构建产物（如 artifacts/, cache/ 等） |

| npm run reinstall | 删除 node_modules 并重新安装依赖 |

| npm run ts-node -- your-script.ts | 使用 ts-node 直接执行任意 TypeScript 脚本 |

| npx ts-node your-script.ts | 直接通过 npx 执行 TypeScript 脚本（无需 npm run） |

| npx hardhat clean | 清理 Hardhat 编译缓存和构建产物（包括 artifacts/ 和 cache/ 目录） |

| npx tsc | 将 TypeScript 文件编译为 JavaScript（需确保 tsconfig.json 配置正确） |

✅ ts-node 使用场景说明：

当本人编写了一些独立的 TypeScript 脚本（例如用于数据处理、API 调用、批量操作等），但不想将其作为 Hardhat 任务运行时，可以使用 ts-node 直接执行：

# 创建一个独立的工具脚本
echo 'console.log("Hello from ts-node!");' > tools/hello.ts

# 执行该脚本
npx ts-node tools/hello.ts

输出：

Hello from ts-node!

优势：

• 无需编译即可运行 .ts 文件。

• 支持 ES6+ 语法和 TypeScript 类型检查。

• 适合快速原型开发和调试工具脚本。

⚠️ 十、安全审计问题说明与处理建议

执行 npm install 后运行 npm audit 可能出现 13 条低危漏洞，主要涉及：

• cookie <0.7.0 → @sentry/node → hardhat

• tmp <=0.2.3 → solc

🔍 问题分析

1. 根源：这些漏洞来自 hardhat 及其依赖链（如 @sentry/node, solc），属于开发工具链的间接依赖。

2. 影响范围：仅限于本地开发环境，不会影响：

   • 智能合约代码本身

   • 部署到链上的字节码

   • 钱包私钥或用户资产

3. 无法修复原因：

   • hardhat@2.26.3 依赖 @sentry/node@^7.59.0，而该版本依赖 cookie@^0.5.0。

   • solc 依赖 tmp，但 solc 已通过安全审计，且 tmp 的漏洞在编译场景下不可利用。

✅ 处理建议

# 接受警告（推荐）
npm audit --omit=dev

或者，若需消除报告：

npm audit fix --force

但请注意：--force 可能引入不兼容版本，不推荐在生产项目中使用。

📌 结论

• ✅ 这些漏洞不影响合约安全性或功能。

• ✅ 当前依赖组合（hardhat@2.26.3 + toolbox@^4.0.0）是经过验证的稳定方案。

• ❌ 不要为了“0漏洞”而升级至 hardhat@3.x，那将引入更大的兼容性风险。

✅ 十一、结论

本方案已完全规避 hardhat@3.x 的不稳定性，精准构建于 v2.26.3：

• ✅ 项目名称已更新为 hardhat-project，所有相关引用均已同步。

• ✅ 强制安装 hardhat@2.26.3，避免 3.0.4 的兼容性问题。

• ✅ 明确解释 Do you want to install ... dependencies? (Y/n) 选项，推荐 y。

• ✅ 清晰区分初始结构与最终结构，便于理解配置演变过程。

• ✅ 所有配置与本人提供的文件100% 一致。

• ✅ 项目可编译、测试、部署、格式化。

• ✅ 在 Node.js v20.18.0 + npm 10.8.2 下验证通过。

• ✅ 完整结构：包含 node_modules/ 目录，反映真实项目状态。

• ✅ 团队协作友好：通过 .editorconfig, .prettierrc, .eslintrc.js, .vscode/settings.json 实现代码风格统一。

• ✅ 新增 ts-node 执行能力：支持直接运行 .ts 脚本，提升开发效率。

• ✅ 已修复 Ignition 导入错误：hardhat@2.26.3 不支持 hardhat-ignition，已移除相关代码并使用标准 ethers.deployContract。

• ✅ 已修复 Solidity 编译器版本不匹配：在 hardhat.config.ts 中明确设置 version: "0.8.28"。

• ✅ 已修复 VS Code TypeScript 错误：详细说明了 node_modules/@nomicfoundation/hardhat-toolbox/src/tsconfig.json 报错的根本原因，并提供了推荐的非侵入式解决方案（修改 .vscode/settings.json 或 tsconfig.json 的 exclude），避免修改 node_modules。

• ✅ 特别说明：hardhat@2.26.3 不支持 hardhat-ignition，该功能是 hardhat@3.x 的实验性功能。已提供基于 ethers.deployContract() 的稳定替代方案，并详细说明了原因和操作步骤。

✅ 此为当前最稳定、最可靠的 Hardhat 开发环境搭建方案。

✅ 安装成功！现在可以安全地进行智能合约开发了！ 🎉

📄 Hardhat 单文件编译指南

本文档详细说明如何在 Hardhat 项目中实现 通用、简单、通过命令指定文件名编译单个 Solidity 文件 的方法，并解决常见问题。

🧩 1. 背景

npx hardhat compile 是 Hardhat 的默认编译命令，但它：

• ❌ 不支持直接编译单个 .sol 文件（如 npx hardhat compile Contract.sol）

• ✅ 支持增量编译：只重新编译修改过的文件

因此，若要实现“指定文件编译”，需借助自定义脚本或配置。

🔧 2. solc 版本兼容性说明

当前配置（package.json）

"devDependencies": {
  "solc": "^0.8.30"
}

是否兼容？

• ✅ 技术上可用

• ❌ 不推荐使用 ^0.8.30

原因

• npx hardhat compile 使用的是 Hardhat 内部管理的 solc，版本由 hardhat.config.js 决定

• package.json 中的 solc 仅用于自定义脚本（如 require('solc')）

• 若脚本与 Hardhat 使用的版本不一致，可能导致：

  • ABI 不一致

  • 部署验证失败

  • 字节码差异

✅ 推荐做法

确保 solc 版本与 hardhat.config.js 一致：

// hardhat.config.js
module.exports = {
  solidity: "0.8.8", // ← Hardhat 实际使用的版本
};

# 安装精确匹配的 solc
npm install solc@0.8.8 --save-dev

"devDependencies": {
  "solc": "0.8.8"
}

✅ 避免版本混乱，确保一致性。

⚠️ 3. 常见错误：Invalid EVM version requested

错误信息

❌ Compilation failed:
Invalid EVM version requested.

原因

在 solc 编译配置中设置了不支持的 evmVersion：

evmVersion: 'paris'

• paris 是 最新升级后的 EVM 版本

• solc <= 0.8.19 不支持 paris

• 最高支持版本为 london

✅ 解决方案

方法 1：删除 evmVersion（推荐）

让 solc 使用默认 EVM 版本，自动兼容：

settings: {
  optimizer: {
    enabled: true,
    runs: 200
  }
  // 不指定 evmVersion
}

方法 2：改为兼容版本

evmVersion: 'london'

方法 3：升级 solc（如需 paris）

npm install solc@0.8.20 --save-dev

然后可安全使用：

evmVersion: 'paris'

✅ 4. 通用单文件编译脚本（推荐）

目标

• 一行命令编译任意 .sol 文件

• 支持参数传入

• 输出 ABI 和 BIN

• 兼容现有 Hardhat 项目

步骤 1：安装 solc

npm install solc@0.8.8 --save-dev

✅ 版本需与 hardhat.config.js 一致

步骤 2：创建脚本 scripts/compile-sol.js

// scripts/compile-sol.js
const fs = require('fs');
const path = require('path');
const solc = require('solc');

const DEFAULT_SOLC_VERSION = '0.8.8';
const OUTPUT_DIR = path.join(__dirname, '..', 'artifacts', 'compiled');

if (!fs.existsSync(OUTPUT_DIR)) {
  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
}

function help() {
  console.log(`
Usage: node scripts/compile-sol.js <SolidityFile.sol> [options]

Options:
  --version, -v <version>   Specify Solidity version (default: ${DEFAULT_SOLC_VERSION})
  --optimize, -o            Enable optimizer (default: true)
  --runs <n>                Set optimizer runs (default: 200)
  --help, -h                Show this help

Example:
  node scripts/compile-sol.js contracts/SimpleStorage.sol
  node scripts/compile-sol.js contracts/Token.sol --version 0.8.20
  `);
  process.exit(0);
}

const args = process.argv.slice(2);
if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
  help();
}

const filePath = args[0];
let optimize = true;
let runs = 200;

for (let i = 1; i < args.length; i++) {
  if (args[i] === '--optimize' || args[i] === '-o') {
    optimize = true;
  } else if (args[i] === '--runs') {
    runs = parseInt(args[++i]);
  }
}

if (!fs.existsSync(filePath)) {
  console.error(`❌ File not found: ${filePath}`);
  process.exit(1);
}

const source = fs.readFileSync(filePath, 'utf8');
const fileName = path.basename(filePath);
const contractName = fileName.replace('.sol', '');

console.log(`🔨 Compiling ${fileName} with solc ${solc.version()}...`);

const input = {
  language: 'Solidity',
  sources: {
    [fileName]: {
      content: source,
    },
  },
  settings: {
    outputSelection: {
      '*': {
        '*': ['abi', 'evm.bytecode.object'],
      },
    },
    optimizer: {
      enabled: optimize,
      runs: runs,
    }
    // ✅ 不设置 evmVersion，避免兼容问题
  },
};

const output = JSON.parse(solc.compile(JSON.stringify(input)));

if (output.errors) {
  const errors = output.errors.filter(e => e.severity === 'error');
  if (errors.length > 0) {
    console.error('❌ Compilation failed:');
    errors.forEach(err => console.error(err.formattedMessage));
    process.exit(1);
  }
}

const contracts = output.contracts[fileName];
const firstContract = Object.keys(contracts)[0];
const contract = contracts[firstContract];

const abiPath = path.join(OUTPUT_DIR, `${contractName}.abi.json`);
const binPath = path.join(OUTPUT_DIR, `${contractName}.bin`);

fs.writeFileSync(abiPath, JSON.stringify(contract.abi, null, 2));
fs.writeFileSync(binPath, contract.evm.bytecode.object);

console.log(`✅ Compiled: ${fileName}`);
console.log(`   ABI:  ${abiPath}`);
console.log(`   BIN:  ${binPath}`);

步骤 3：添加 npm script

"scripts": {
  "compile:sol": "node scripts/compile-sol.js"
}

步骤 4：使用方式

# 编译 SimpleStorage.sol
npm run compile:sol contracts/SimpleStorage.sol

# 指定优化次数
npm run compile:sol contracts/Token.sol -- --runs 1000

# 查看帮助
node scripts/compile-sol.js --help

输出示例

🔨 Compiling SimpleStorage.sol with solc 0.8.8...
✅ Compiled: SimpleStorage.sol
   ABI:  artifacts/compiled/SimpleStorage.abi.json
   BIN:  artifacts/compiled/SimpleStorage.bin

📂 输出目录结构

artifacts/
└── compiled/
    ├── SimpleStorage.abi.json
    └── SimpleStorage.bin

🔄 5. npx hardhat compile 行为说明

运行：

npx hardhat compile

输出：

Nothing to compile
No need to generate any newer typings.

✅ 是否正常？

是！这是正常行为。

• 表示合约未修改，Hardhat 使用缓存

• TypeChain 也无需重新生成类型

强制重新编译

# 方法 1：强制编译
npx hardhat compile --force

# 方法 2：清理后编译
npx hardhat clean
npx hardhat compile

✅ 6. 总结与最佳实践

| 项目 | 推荐做法 |

|------|---------|

| solc 版本 | 与 hardhat.config.js 一致，精确版本 |

| 单文件编译 | 使用 compile-sol.js 脚本 |

| EVM 版本 | 不设置 evmVersion，让编译器自动选择 |

| 增量编译 | 日常开发使用 npx hardhat compile |

| 类型生成 | 由 Hardhat Toolbox 自动管理 |

🚀 下一步建议

# 编译单个文件
npm run compile:sol contracts/SimpleStorage.sol

# 清理并全量编译
npx hardhat clean && npx hardhat compile

# 验证编译产物
ls artifacts/contracts/

📝 文档更新时间：2025年10月3日适用于 Hardhat 2.x + TypeScript 项目

✅ 现在你已拥有一套完整、可靠、可复用的单文件编译方案！

📚 Hardhat 项目中 ESLint & Prettier 集成问题全记录

—— 从 npm run lint 报错到最终稳定方案的完整复盘（2025 精确版）

作者：Rain时间：2025年10月3日目标：完整还原在 Hardhat + TypeScript 项目中，从 npm run lint 报错出发，经历 Solhint 替代 → 验证失败 → 回归 ESLint → 版本冲突排查 → 最终稳定配置的全过程。特别强调：hardhat@2.26.3 与 ESLint v9 不兼容，必须使用 ESLint v8。

🧭 完整问题演进脉络图

1. 起点：npm run lint 执行报错（ESLint 无法处理 .sol）
   ↓
2. 尝试方案 A：引入 solhint 替代检查
   ↓
3. 验证失败：solhint 安装失败、配置不生效、插件废弃
   ↓
4. 回归本质：尝试让 ESLint 支持 .sol 文件
   ↓
5. 错误方向：尝试升级到 ESLint v9 + Flat Config
   ↓
6. 发现根本冲突：hardhat 依赖 eslint@^8.0.0，不兼容 v9
   ↓
7. 正确方向：锁定 ESLint v8 + eslint-plugin-solidity（旧版兼容）
   ↓
8. 最终验证：npm run lint 成功，.sol 文件被检查
   ↓
✅ 解决方案：ESLint v8 + eslint-plugin-prettier + prettier-plugin-solidity

1️⃣ 起点：npm run lint 执行报错

❌ 问题现象

执行：

npm run lint

报错：

Error: Failed to load plugin "solidity" declared in ".eslintrc.js": Cannot find module 'eslint-plugin-solidity'

或：

Error: Parsing error: The keyword 'pragma' is reserved

2️⃣ 尝试方案 A：引入 solhint 作为替代方案

🤔 初始建议（错误方向）

“你可以尝试使用 solhint 来检查 Solidity 文件。”

建议操作：

npm install --save-dev solhint
echo '{ "extends": "solhint:recommended" }' > .solhint.json
npx solhint "contracts/**/*.sol"

✅ 短期效果

• solhint 能独立运行

• 检测出部分 Solidity 问题

⚠️ 但未解决根本问题

• npm run lint 仍然失败（因为 ESLint 仍无法处理 .sol）

• 需要额外运行 npx solhint，流程割裂

3️⃣ 验证失败：solhint 本身问题重重

❌ 问题 1：solhint 安装后命令无法执行

npm install --save-dev solhint@latest
npx solhint
# 错误：command not found

原因：solhint@1.x 为实验版本，发布不完整。

修复：

npm install --save-dev solhint@0.0.13

✅ 成功运行，但版本为 2021 年发布，严重过时。

❌ 问题 2：.solhint.json 配置不生效

配置：

{
  "rules": {
    "func-visibility": "error"
  }
}

结果：无报错，规则未触发。

排查：solhint --print-config 显示配置未加载。

❌ 问题 3：与 Prettier 集成失败

npm install --save-dev solhint-plugin-prettier

.solhint.json：

"plugins": ["prettier"],
"rules": { "prettier/prettier": "error" }

结果：无格式化提示，插件未生效。

结论：solhint-plugin-prettier 最后更新于 2020 年，已废弃。

❌ 问题 4：VS Code 插件不兼容

• 安装 “Solhint” VS Code 插件

• 无波浪线提示

• 插件市场评论：“已停止维护”

4️⃣ 回归本质：尝试让 ESLint 支持 .sol 文件

🤔 新思路

“能否让 ESLint 直接解析 .sol 文件？”

🔍 发现 eslint-plugin-solidity

• npm 包：eslint-plugin-solidity

• 作用：让 ESLint 支持 Solidity 语法

• 关键点：该包最后更新为 2020 年，且不支持 ESLint v9

5️⃣ 错误方向：尝试升级到 ESLint v9 + Flat Config

❌ 尝试升级 ESLint

npm install --save-dev eslint@^9.0.0

❌ 执行 npm run lint 报错

Error: The plugin "@nomicfoundation/hardhat-toolbox" requires an ESLint version ^8.0.0

🔍 深入排查

查看 @nomicfoundation/hardhat-toolbox 的 package.json：

"devDependencies": {
  "eslint": "^8.0.0"
}

✅ 确认：hardhat-toolbox 仅兼容 ESLint v8，不支持 v9。

6️⃣ 正确方向：锁定 ESLint v8 + 兼容方案

✅ 决策

放弃 ESLint v9，回归 v8，并寻找 eslint-plugin-solidity 的替代方案。

🔍 新发现

• prettier-plugin-solidity 已支持 格式化 + 基础 linting

• eslint-plugin-prettier 可将 Prettier 的格式化结果暴露为 ESLint 错误

• 可通过 eslint-plugin-prettier 间接实现 .sol 文件的“检查”

7️⃣ 最终解决方案：ESLint v8 + Prettier 统一格式化

✅ 保留现有配置（已正确）

"scripts": {
  "lint": "npm run lint:js && npm run format:check",
  "lint:fix": "npm run lint:js:fix && npm run format",
  "lint:js": "eslint \"**/*.{ts,js}\" --ext .ts,.js",
  "lint:js:fix": "eslint \"**/*.{ts,js}\" --ext .ts,.js --fix",
  "format": "prettier --plugin prettier-plugin-solidity --write \"**/*.{js,cjs,ts,sol}\"",
  "format:check": "prettier --plugin prettier-plugin-solidity --check \"**/*.{js,cjs,ts,sol}\""
}

✅ devDependencies（关键版本）

"devDependencies": {
  "eslint": "^8.57.0",
  "prettier": "^3.2.5",
  "prettier-plugin-solidity": "^1.1.3",
  "eslint-plugin-prettier": "^5.1.3",
  "@typescript-eslint/eslint-plugin": "^7.18.0",
  "@typescript-eslint/parser": "^7.18.0"
}

✅ .eslintrc.js（推荐配置）

// .eslintrc.js
module.exports = {
  root: true,
  env: {
    node: true,
    mocha: true,
  },
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:prettier/recommended", // 启用 eslint-plugin-prettier
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: "module",
    project: "./tsconfig.json",
  },
  plugins: ["@typescript-eslint", "prettier"],
  rules: {
    "prettier/prettier": "error", // Prettier 错误作为 ESLint 错误
    "@typescript-eslint/no-unused-vars": "error",
  },
  ignorePatterns: ["artifacts/", "cache/", "coverage/", "node_modules/"],
};

✅ VS Code settings.json

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": [
    "javascript",
    "typescript",
    "javascriptreact",
    "typescriptreact"
    // ❌ 不添加 "solidity"，因为 ESLint 不直接解析 .sol
  ],
  "solidity.formatter": "prettier",
  "solidity.compileUsingRemoteVersion": "v0.8.20+commit.c7f1c3b1"
}

8️⃣ 最终验证：npm run lint 成功执行

✅ 执行命令

npm run lint

✅ 输出结果

# 1. 执行 lint:js
> eslint "**/*.{ts,js}" --ext .ts,.js

# 2. 执行 format:check
> prettier --plugin prettier-plugin-solidity --check "**/*.{js,cjs,ts,sol}"

# 如果 .sol 文件格式错误，prettier 会报错，导致 lint 失败

✅ 工作流说明

• .ts/.js 文件：由 ESLint 检查 + 自动修复

• .sol 文件：由 Prettier 格式化 + format:check 验证

• npm run lint：统一入口，确保所有文件符合规范

✅ 最终状态

| 功能 | 状态 | 说明 |

|------|------|------|

| npm run lint | ✅ 成功 | 统一检查所有文件 |

| Solidity 检查 | ✅ | 通过 prettier --check 实现 |

| 自动修复 | ✅ | npm run lint:fix 支持 |

| Prettier 集成 | ✅ | 支持 .sol 格式化 |

| VS Code 支持 | ✅ | 格式化 + ESLint 提示 |

📌 复盘总结：技术决策路径

| 阶段 | 决策 | 结果 | 教训 |

|------|------|------|------|

| 1. 起点 | npm run lint 报错 | ❌ | 需先定位错误来源 |

| 2. 尝试 | 引入 solhint | ⚠️ 临时方案 | 替代方案可能引入新问题 |

| 3. 验证 | solhint 失败 | ❌ | 不可靠，生态断裂 |

| 4. 探索 | 尝试 ESLint v9 | ❌ | 与 hardhat 不兼容 |

| 5. 回归 | 锁定 ESLint v8 | ✅ 正确方向 |

| 6. 解决 | 使用 prettier --check 作为 .sol 检查 | ✅ 成功 | 利用现有工具链 |

✅ 最终结论

solhint 已不可靠，不应作为主要 linter。

eslint-plugin-solidity 已废弃，不推荐使用。

hardhat@2.26.3 仅兼容 ESLint v8，不可升级到 v9。

正确方案：

1. 使用 ESLint v8 检查 .ts/.js 文件

2. 使用 prettier-plugin-solidity 格式化 .sol 文件

3. 使用 npm run format:check 作为 .sol 的“检查”手段

4. 通过 npm run lint 统一执行

📎 参考资料

1. hardhat-toolbox package.json（依赖 eslint@^8.0.0）

2. prettier-plugin-solidity

3. eslint-plugin-prettier

复盘完毕。此文档完整还原了从问题提出、错误尝试、版本冲突排查到最终稳定方案的全过程，确保信息真实、路径清晰，特别强调了 hardhat 与 ESLint v9 的不兼容性，可供团队复盘与知识传承。