简介：该教程由ConsenSys团队原作者授权翻译，内容覆盖以太坊客户端与智能合约语言选择，系统性讲解公钥加密、区块链账本、EVM、节点、矿工与工作量证明，以及Gas和以太币的作用；还解释了DApp的架构理念及IPFS等去中心化存储，为后续开发打好概念基础。后半部分聚焦实际操作，介绍如何用geth运行节点、借助testrpc搭建测试网络，并详细演示Truffle的测试与DApp构建流程，让读者能按步骤完成从理论到实践的过渡。资源为单个PDF文件，约356KB，便于离线阅读。教程虽成文较早，但核心概念与开发流程依然扎实，对理解以太坊生态和Solidity开发很有参考价值。已有498人学习，适合作为系统学习智能合约前的第一份指南。
1. 智能合约与Solidity编程教程：先理解“状态”再谈语法
写 Solidity 编程教程的难点，在于它表面上像 JavaScript，实际却是一套完全不同的执行模型。普通程序崩溃了可以重新拉起，变量清空再来一次；而智能合约一旦通过交易部署到链上，代码和状态就长期存在，每次调用都是外部发起的交易，任何未处理的异常都会让整笔交易回滚，还要付出 Gas 成本。这些限制不是语法层面的坎，而是设计层面的边界。这篇文章面向两类读者：一类是刚接触智能合约的开发者，需要一条能直接落地的学习路径；另一类是已经写过一些 Solidity 的老手，想补上部署、验证和 Gas 调优这些容易被忽略的环节。我会按一条真实项目的推进顺序展开：先搭环境，再啃语言特性，然后部署到测试网做源码验证，最后用六个具体写法把 Gas 和安全一起收口。
2. 搭一套 Solidity 本地区块链开发环境：Hardhat 的最小可复现清单
2.1 为什么生产级智能合约开发不用网页 IDE
Remix 在浏览器里写合约，非常适合初学语法和快速验证小片段。但真实项目至少要面对自动化测试、多网络部署、私钥管理、脚本执行这些需求，网页 IDE 不能满足。常见做法是使用 Hardhat 或 Foundry。Hardhat 的优势在于插件生态成熟，JavaScript/TypeScript 工程师上手快，Ethers.js 和 Waffle 的配合资料也最多；Foundry 的优势在于用 Solidity 直接写测试，执行速度快。对于大多数后端转过来的开发团队，我一般建议先从 Hardhat 开始，等需要大量模糊测试和分叉测试时再引入 Foundry，两者并不冲突。
| 工具 | 定位 | 测试语言 | 适合场景 |
|---|---|---|---|
| Remix | 网页编辑器 | Solidity | 单文件验证、教学演示 |
| Hardhat | 本地开发框架 | JavaScript / TypeScript | 工程化项目、多网络部署 |
| Foundry | 本地开发框架 | Solidity | 复杂测试、EVM 分叉、Gas 对比 |
选择 Hardhat 还有一个现实原因：它的hardhat-toolbox插件把部署、测试、verify、console 等功能打包好了，减少配置文件的踩坑成本。尤其是“编写智能合约编程教程”常常只讲语法，不讲工具链，导致读者写完合约不知道怎么部署到测试网。下面这套流程就是专门补上这一段的。
2.2 用 Hardhat 初始化项目、配置编译器和跑通第一个合约
先保证本机安装 Node.js 18 以上的 LTS 版本，然后执行下面的命令：
mkdir solidity-tutorial cd solidity-tutorial npm init -y npm install --save-dev hardhat npx hardhat init在npx hardhat init出现交互选项时，选择Create a JavaScript project，其余选项默认即可。初始化完成后，项目里会生成contracts、scripts、test三个目录，以及hardhat.config.js配置文件。
接下来在contracts目录下新建Counter.sol，写入一个最简单的状态合约：
// SPDX-License-Identifier: MIT pragma solidity ^0.8.18; contract Counter { uint256 private count; address private owner; constructor() { owner = msg.sender; } function increment() external { require(msg.sender == owner, "only owner"); count += 1; } function getCount() external view returns (uint256) { return count; } }然后执行编译：
npx hardhat compile编译通过后，artifacts目录里会生成对应 ABI 和字节码。这里有两个关键点需要说明：第一，owner和count是状态变量，会永久保存在链上，每次调用increment修改的不是本地副本，而是合约保存槽位里的值；第二，require里的错误信息字符串确实会被编译进字节码，占用合约体积和调用时的 Gas，后面会讲更省气的替代方案。
2.3 编译配置里的优化器参数怎么调
默认生成的hardhat.config.js足够跑通示例，但真实项目通常会手动指定 Solidity 版本和优化器参数。下面是一份更明确的配置：
require('@nomicfoundation/hardhat-toolbox'); module.exports = { solidity: { version: '0.8.24', settings: { optimizer: { enabled: true, runs: 200 } } } };参数说明：version指定编译器版本，一般建议与合约文件里的pragma保持一致；optimizer.enabled开启优化后，编译器会尝试用更短的字节码表达相同逻辑；runs表示期望合约在链上被调用多少次。runs数字越大，编译器就越倾向于消耗更多部署 Gas 来换取更低的每次调用成本。对于低频使用的合约，runs: 1能让部署便宜不少；对于高频交易合约，runs: 2000更合理。
编译出错时，按错误类型定位比较快：ParserError通常是 pragma 写错或缺分号；TypeError常见于函数可见性缺失或类型不匹配；DeclarationError多半是状态变量重名；UnimplementedFeatureError往往出现在 ABI coder 版本切换时。这些错误信息都会直接给出文件路径和行号，不需要额外工具。
3. Solidity 语言的关键边界：类型、存储位置、可见性与事件
3.1 数据位置 storage、memory、calldata 的分工
Solidity 引用类型数组、结构体、映射，必须显式声明数据位置。storage指向合约持久存储区，写入会被保留；memory是一次性内存区域，函数调用结束后销毁；calldata是外部调用传入的不变数据区，只读且最省 Gas。
contract StorageDemo { uint256[] private values; function batchStore(uint256[] calldata input) external { for (uint256 i = 0; i < input.length; i++) { values.push(input[i]); } } function getValue(uint256 index) external view returns (uint256) { return values[index]; } }上面的代码中，input声明为calldata，因为它只在函数内读取，不需要复制进 memory；values是storage数组。注意calldata数组没有push、pop方法，所以写入前必须复制到memory或直接写入storage。
新手最常犯的错误是把calldata写成memory，结果多付一次数据复制的 Gas；更大的坑是在内部函数之间传递storage引用时，某个函数修改了状态变量，导致调用方看到的数值被意外改变。这里的原则是：只读参数优先calldata，需要修改的临时数组用memory，需要持久化则直接操作storage状态变量。
3.2 函数可见性、状态可变性修饰符和错误处理
函数可见性直接决定谁能调用：external只能从合约外部调用，public内外都可调，internal只有本合约和继承合约能调，private仅限本合约。状态可变性修饰符view表示读取链上状态但不修改，pure表示不读取也不修改。EVM 层面对view函数的外部调用不产生 Gas 消耗，但链上内部调用依然计费，因为打包进交易后仍然需要执行字节码。
错误处理在 Solidity 0.8 之后推荐优先用自定义错误：
error NotOwner(address caller); contract AdminAction { address public immutable owner; constructor() { owner = msg.sender; } function adminOnly() internal view { if (msg.sender != owner) { revert NotOwner(msg.sender); } } function doSomething() external { adminOnly(); // do something } }自定义错误会把错误签名和参数一起编码进 revert 数据，比require(false, "string")更节省 Gas，也更容易被前端解析。require适合验证外部输入是否满足条件，比如余额不足、金额范围等；assert只用于验证内部不变量，使用不当会消耗全部剩余 Gas，生产环境里应该极少出现。记住这个优先级：revert + 自定义错误>require + 无字符串>require + 短字符串。
3.3 事件与索引参数：链上日志的检索入口
事件是 Solidity 与外部世界沟通的主要方式。事件写入交易日志，不是状态存储，所以单位成本远低于修改状态变量。每个事件最多有三个indexed参数，这些参数会被单独建索引，供钱包和区块浏览器检索。
event Transfer(address indexed from, address indexed to, uint256 amount); function transfer(address to, uint256 amount) external { // 转出逻辑 emit Transfer(msg.sender, to, amount); }indexed参数可以通过地址精确过滤，例如查询某个地址收到的所有转账记录。但indexed只提供高效过滤，不能解决事件数据本身的解码问题；未索引的参数会被放进日志的 data 区，节点同步时需要完整 ABI 才能正确显示。因此事件字段设计要避免把所有关键信息都堆到 data 区，最理想的是把地址和金额组合成两个indexed，再加一个备注字段到 data 区。对于字符串类型，indexed会把哈希算出来，基本无法反向还原，不太适合做检索条件。
4. 部署到测试网并做源码验证：一条完整的上线链路
4.1 编写部署脚本并配置多网络
本地编译通过只是第一步，真正要验证合约能否在公开网络运行，需要部署到测试网。先在hardhat.config.js里配置网络：
require('@nomicfoundation/hardhat-toolbox'); require('dotenv').config(); module.exports = { solidity: '0.8.24', networks: { sepolia: { url: process.env.SEPOLIA_RPC_URL, accounts: [process.env.PRIVATE_KEY] } } };生产环境不要直接 commit 私钥，用dotenv加载.env文件是一个常见做法。.env文件内容如下：
SEPOLIA_RPC_URL=https://your-rpc-provider.example PRIVATE_KEY=0x...部署脚本放在scripts/deploy.js：
const { ethers } = require('hardhat'); async function main() { const Counter = await ethers.getContractFactory('Counter'); const counter = await Counter.deploy(); await counter.waitForDeployment(); console.log('Counter deployed to:', counter.target); } main().catch((error) => { console.error(error); process.exitCode = 1; });执行命令：
npx hardhat run scripts/deploy.js --network sepolia参数说明：getContractFactory会根据hardhat.config.js里的编译产物实例化合约工厂；deploy()返回合约部署交易对象；waitForDeployment()会等待交易确认，确保拿到已存活的部署地址。这里有一个容易忽略的点：Hardhat 默认的网络是内置的hardhat，它不会向真实网络广播，所以不写--network时部署结果只存在于本地模拟环境。
4.2 水龙头、Gas 与 nonce 冲突的排查
部署前需要测试币支付 Gas。测试币的水龙头通常要求你提供测试网钱包地址，然后定时发放一定数量。领取后先确认钱包中有余额，再执行部署命令。以下表格是最常见的部署失败原因：
| 现象 | 实际原因 | 处理方式 |
|---|---|---|
insufficient funds | 钱包没有测试币 | 去水龙头领取足够 ETH |
nonce too low | 交易 nonce 低于链上当前值 | 检查钱包是否有 pending 交易，等待或清除 |
transaction underpriced | Gas 上限低于矿工接受值 | 提高maxPriorityFeePerGas或maxFeePerGas |
execution reverted | 合约构造或部署逻辑抛出异常 | 在本地测试网运行脚本，打开 Hardhat console 追踪 |
nonce 冲突在本地大量发送交易时尤其常见。Hardhat 会维护一个内存中的 nonce 计数器，但如果你的私钥同时在多个脚本里使用，就会出现两个脚本发送相同 nonce 的交易，最终只有一个上链。遇到这类情况，优先用区块浏览器查看账户正在确认和 pending 的交易，再决定是等待还是显式设置nonce。
4.3 用 hardhat verify 校验合约源码
部署成功并不等于合约可以被信任，外部用户只能看到字节码，无法直接验证它是否与源码一致。为了把源码附加到区块浏览器，需要引入@nomicfoundation/hardhat-verify，并在配置里加入对应浏览器的 API key。
安装并配置完成后，执行以下命令：
npx hardhat verify --network sepolia DEPLOYED_CONTRACT_ADDRESS如果构造函数带参数，还要把参数按顺序跟在地址后面。验证失败最常见的原因有三个：编译优化器设置和实际部署时不匹配；Solidity 版本写得太宽导致浏览器无法锁定同一个编译版本；带有构造函数参数时没有把参数编码成 ABI 格式。验证通过后，用户可以直接在区块浏览器页面上读取函数返回值或调用getCount，不需要自己跑一遍部署脚本。
5. 让 Solidity 合约省 Gas 又安全的六个写法
5.1 用 immutable 替代只读状态变量
部署时确定、之后不再修改的值，例如 owner、合约地址、质押代币地址，应该用immutable。这个关键字让编译器把值直接写入合约字节码，读取时不需要通过SLOAD从存储槽读取，节省 Gas 也减少攻击面。构造函数里对immutable赋值一次后，就不要再尝试修改。
5.2 自定义错误放在函数退出路径最前面
用error写清晰的错误类型，同时把条件判断放在函数最前面，尽早 revert。例如转账前先检查余额，再检查接收地址，这样不会执行后面的计算，也不会产生无意义的存储写入。错误信息越短，revert 时的成本越低。
5.3 循环内避免读写 storage
每次读写 storage 的 Gas 成本远高于 memory 或 calldata。如果要在循环里汇总某个状态数组，先把这个数组复制到 memory 再遍历，最后一次性写回 storage。如果数组长度可能很大，优先考虑分页处理或多笔交易完成，避免单笔交易 Gas 超过区块上限。
5.4 用位运算打包多个布尔状态
四个bool状态变量会占用四个 32 字节槽位，改用uint256按位存储可以把它们塞进一个槽位，读写成本大幅下降。这个技巧在多重权限控制场景里很有用。代价是代码可读性下降，建议把掩码常量命名清楚，并用测试覆盖所有组合。
5.5 在安全边界内使用 unchecked
Solidity 0.8 默认打开整数溢出检查，但有些场景可以安全跳过。例如循环计数器i++不会超过数组长度，可以用unchecked { i++; }节省 Gas。注意unchecked只影响该代码块内的算术运算，不会影响其他逻辑。
5.6 外部调用必须设置明确的失败处理
合约间调用如果使用address.call或transfer，要注意返回值处理。transfer固定发送 2300 Gas，功能受限；call会把恶意合约的完整逻辑执行起来，必须有返回值判断或配合重入锁。我的建议是：对外部调用一律写清楚“成功才继续”的分支，不要默认调用一定成功。
以上六个写法的共同点，是把“能不能跑”和“能不能省着跑”分开思考。部署前跑一遍 Gas 报告，例如npx hardhat gas-report，对比同样逻辑在不同写法下的成本，是快速掌握这些细节的最佳方式。
本文还有配套的精品资源，点击获取
