# Web3.py 教程：用 Python 开发以太坊应用的完整指南

By [区块链查询](https://paragraph.com/@0x99eb2595af345e27d1a488bac1c769e8cb05b672) · 2025-09-10

---

[Web3.py](http://Web3.py) 是以太坊官方推出的 Python 客户端库，有了它，开发者只需数行 Python 代码即可与 **以太坊区块链** 交互。本文将带你从零开始连接节点、查询链上数据、核验地址、发送交易并与智能合约函数互动。每一个步骤都配有实战代码片段，学完即可快速上手 **区块链开发**。

* * *

Web 3.0 与区块链基础
--------------

### 什么是 Web 3.0

Web 2.0 以中心化平台为核心，数据主权集中；而 **Web 3.0** 的目标是“去中心化”。在 Web 3.0 网络里，所有节点共同维护同一账本，用户数据由用户自己掌控。通过密码学与点对点协议，Web 3.0 实现了无需可信第三方的价值流通，**DApp（去中心化应用）**、NFT、DAO 都是它的典型落地场景。

### 你需要了解的术语

*   **节点**：保存区块链完整或部分数据，可供我们查询交易、余额、合约状态等信息
    
*   **区块**：若干笔交易被打包在一起形成的数据集合，每个区块通过哈希指向前一个区块
    
*   **区块链**：由区块按时间顺序串联而成的分布式账本，没有中心管理方
    
*   **交易**：由用户签名发起，可能导致账户余额或合约状态变化的链上指令
    

* * *

准备工作
----

*   Python 3.8+ 阅读本文你只需要会基础 Python，并能在终端执行命令
    
*   一台可联网的电脑（macOS / Windows / Linux 均可）
    
*   提前准备好一个 **以太坊节点** 连接入口
    

👉 [点此直接体验无需自己搭节点即可查询链上数据的快感](https://okxdog.com/)

### 选用以太坊节点

自建节点需要同步上百 GB 数据，个人学习推荐 **Infura** 这类托管节点。

1.  注册 Infura，创建 Project，复制 `https://mainnet.infura.io/v3/<你的项目ID>`
    
2.  将 URL 保存到 `.env` 文件（别忘了把 `.env` 加入 `.gitignore` 防止密钥泄漏）
    

    # .env
    INFURA_URL=https://mainnet.infura.io/v3/xxxxxxxxxxxxxxxx
    

* * *

安装 [web3.py](http://web3.py) 并连接节点
----------------------------------

    python -m venv venv && source venv/bin/activate   # 创建虚拟环境
    pip install web3 python-decouple
    

新建 `test_web3.py`：

    from web3 import Web3
    from decouple import config
    
    infura_url = config('INFURA_URL')
    w3 = Web3(Web3.HTTPProvider(infura_url))
    print("已连接？", w3.isConnected())
    

运行脚本，看到 `True` 表示连接成功。

* * *

查询以太坊区块链
--------

### 获取最新区块

    latest_block = w3.eth.get_block('latest')
    print(latest_block['number'], latest_block['hash'].hex())
    

### 核验以太坊地址

    >>> w3.isAddress('0x6dAc6E2Dace28369A6B884338B60f7CbBF7fb9be')
    True
    

转换为 **Checksummed Address**（避免交易前因大小写出错）：

    addr = w3.toChecksumAddress('0xd7986a11f29fd623a800adb507c7702415ee7718')
    balance_wei = w3.eth.get_balance(addr)
    balance_eth = w3.fromWei(balance_wei, 'ether')
    print(f"该地址持有 {balance_eth} ETH")
    

* * *

### 常见疑问 FAQ

\*\*Q1：\*\*为什么需要将地址转换成 Checksummed Address？\*\*A：\*\*以太坊只接受带校验和的地址格式，可减少转账到错误地址的风险。

**Q2：**`fromWei` 这个方法会改变链上余额吗？\*\*A：\*\*不会，它只是单位换算工具，链上数据保持不变。

\*\*Q3：\*\*查询时每次都返回字节类型，如何转成可读格式？\*\*A：\*\*使用 `.hex()` 可轻松将 `HexBytes` 转为十六进制字符串。

\*\*Q4：\*\*Infura 提供免费额度吗？\*\*A：\*\*有，个人日调用量少于 10 万次即可永久免费。

\*\*Q5：\*\*怎样查询历史交易记录？\*\*A：\*\*获取交易哈希后，使用 `w3.eth.get_transaction(tx_hash)` 可获得完整交易详情。

* * *

与智能合约互动
-------

### 获取合约 ABI 和地址

在 [Etherscan](https://etherscan.io/) 搜索任意代币（例如 SHIBACHU 合约地址 `0xd665ce...`），复制合约 ABI JSON。

    address = '0xd665ce6Ef8AdA72B1CF946A6a71508bDD6D2EE04'
    abi = json.loads('<上一步粘贴的ABI>')
    contract = w3.eth.contract(address=address, abi=abi)
    
    # 读取 totalSupply
    total = contract.functions.totalSupply().call()
    print(f"总发行量: {w3.fromWei(total, 'ether')} 枚")
    

### 查询任意账户的代币余额

    holder = '0x123...'
    balance = contract.functions.balanceOf(holder).call()
    print(f"该账户拥有 {w3.fromWei(balance, 'ether')} 枚代币")
    

* * *

在以太坊链上发送交易
----------

发送交易需要 **本地签署**，因此必须获得私钥并存放在安全位置，例如:

    from eth_account import Account
    
    acct = Account.from_key('0x你的私钥')
    tx = {
        'to': '0x接收地址',
        'value': w3.toWei(0.01, 'ether'),
        'gas': 21000,
        'gasPrice': w3.toWei('10', 'gwei'),
        'nonce': w3.eth.getTransactionCount(acct.address),
        'chainId': 1
    }
    
    signed = acct.sign_transaction(tx)
    tx_hash = w3.eth.sendRawTransaction(signed.rawTransaction)
    print("交易哈希:", tx_hash.hex())
    

👉 [三分钟无代码体验链上交互，实时查看交易区块高度与收入收益](https://okxdog.com/)

* * *

### 智能合约交互 FAQ

\*\*Q1：\*\*怎么知道自己调用的是只读函数还是写链函数？\*\*A：\*\*ABI 内 `stateMutability` 字段为 `view` / `pure` 表示只读，否则需发起交易并付 gas 费。

\*\*Q2：\*\*ABI 太长，本地难以维护，有简化方案吗？\*\*A：\*\*可把 ABI 托管在 IPFS，或在构建脚本中自动下载并缓存到 `abi/` 文件夹。

\*\*Q3：\*\*网络拥堵 gas 费太高怎么办？\*\*A：\*\*使用 `maxFeePerGas` 与 `maxPriorityFeePerGas` 设置 EIP-1559 费率，等待低峰再发交易。

\*\*Q4：\*\*能否批量查询多个地址余额？\*\*A：\*\*可以结合 `multicall` 合约一次打包多条查询，显著降低 RPC 调用次数。

* * *

代码示例仓库与下一步
----------

*   GitHub 示例仓库（已开源）：`git clone https://github.com/firebase007/web3.py`
    
*   充分阅读 [web3.py 官方文档](https://web3py.readthedocs.io/en/stable/examples.html) 可解锁高级功能：日志监听、事件过滤、离线签署、链上索引等。
    

当你完成本教程后，你的 Python 控制台已经成功与 **以太坊主网** 建立了面向未来的桥梁：读取世界状态、验证地址、调用智能合约函数，甚至还能自主发起转账。现在开始把业务逻辑写进智能合约，前端通过 [Web3.py](http://Web3.py) 调用，你就拥有了一个真正意义上的 **去中心化应用**。

祝你构建愉快，May the blocks be with you!

---

*Originally published on [区块链查询](https://paragraph.com/@0x99eb2595af345e27d1a488bac1c769e8cb05b672/web3-py-python)*