Sepolia Ethereum RPC：端点设置、水龙头和调试

Sepolia 是大多数以太坊开发者首先使用的测试网。它在 JSON-RPC 层的行为与主网类似，因此在以太坊主网上运行的合约、钱包和索引器通常只需更改链 ID 和端点即可在 Sepolia 上运行。摩擦很少来自协议本身——而是选择可用的端点、为账户提供资金以及诊断请求失败的原因。

本页面是一个工作参考：确切的链设置、选择端点类型的决策指南、可以粘贴到终端中的请求示例，以及针对最可能遇到的错误的调试路径。

你应该使用哪个 Sepolia 端点？

有三种实用选项，正确的选择取决于你在做什么，而不是个人偏好。

• 本地或一次性测试。 公共端点通常就足够了。你发送少量请求，不关心速率限制，如果某个端点慢可以切换。
• 团队开发和预发布。 托管 RPC API 为你提供 API 密钥、跨机器的一致配置，以及出现问题时支持路径。这是最终将发布到主网的应用程序的常见选择。
• CI 管道、索引器和负载测试。 这些会产生持续的请求量，通常需要归档数据或广泛的日志查询。专用节点消除了噪声邻居效应，并允许你根据工作负载调整容量。

OnFinality 通过其 RPC API 服务 和 专用节点 提供 Sepolia，当你需要隔离容量时。你可以在 Sepolia RPC 页面 上查看网络条目。

如果你仍在公共、托管和专用基础设施之间做一般性决定，RPC 提供商选择指南 更深入地介绍了评估标准。

Sepolia 链设置一览

在将 Sepolia 添加到钱包、框架配置或部署脚本时使用这些值。它们与以太坊工具中使用的网络定义一致。

一个公共 OnFinality Sepolia 端点可用于轻量测试：

https://eth-sepolia.api.onfinality.io/public

公共端点是共享的，旨在用于开发和评估。对于类似生产的工作负载，请使用 API 密钥或专用节点，这样你的流量就不会与其他用户竞争。

从钱包连接

Sepolia 上的大多数钱包连接问题来自链 ID 不匹配或端点过时。手动添加网络时，请准确输入链 ID 11155111——不要带分隔符的十进制字符串，也不要主网链 ID 1。

如果你使用的是支持程序化网络切换的浏览器钱包，可以直接请求链：

// Request Sepolia from an injected wallet
await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [{
    chainId: "0xaa36a7", // 11155111 in hex
    chainName: "Ethereum Sepolia",
    nativeCurrency: { name: "Sepolia Ether", symbol: "ETH", decimals: 18 },
    rpcUrls: ["https://eth-sepolia.api.onfinality.io/public"],
    blockExplorerUrls: ["https://sepolia.etherscan.io"]
  }]
});

注意，钱包请求中的 chainId 是十六进制编码的。相比之下，JSON-RPC 调用也以十六进制字符串返回链 ID，因此 Sepolia 上的 eth_chainId 返回 0xaa36a7。如果你的应用程序将该值与十进制 11155111 进行比较，检查将失败——在比较之前解析它。

从水龙头获取测试 ETH

Sepolia ETH 没有市场价值，但你仍然需要它来部署合约和发送交易。水龙头通常需要以下之一：

• 在水龙头提供商处验证的账户。
• 少量主网余额，用作反滥用信号。
• 工作量证明或社交登录步骤。

节省时间的实用说明：

1. 为你实际部署的地址提供资金。 很容易将 ETH 请求到新地址，然后从另一个地址部署。
2. 预期冷却时间。 大多数水龙头限制同一地址或 IP 请求资金的频率。
3. 不要将主网 ETH 桥接到 Sepolia。 没有支持的桥接路径；请使用水龙头。
4. 保留少量缓冲。 合约部署加上几笔测试交易通常就足够了，但具有大字节码的复杂部署会消耗更多 gas。

如果水龙头交易长时间待处理，请在再次请求之前检查浏览器——向同一地址重复请求很少有帮助，并且可能触发速率限制。

进行你的第一次 JSON-RPC 调用

在将 Sepolia 接入应用程序之前，确认端点响应并报告预期的链。一个 curl 调用可以回答这两个问题。

curl -s https://eth-sepolia.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_chainId",
    "params": []
  }'

健康的响应如下所示：

{"jsonrpc":"2.0","id":1,"result":"0xaa36a7"}

如果你看到 0x1，那么你正在与以太坊主网通信，而不是 Sepolia。如果你看到错误对象，端点可达但拒绝了请求——在更改其他任何内容之前检查错误代码。

在设置期间还值得运行另外两个调用：

# Current block height
curl -s https://eth-sepolia.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# Balance of an address, in wei (hex)
curl -s https://eth-sepolia.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xYourAddress","latest"]}'

eth_blockNumber 确认节点已同步并跟随链。eth_getBalance 确认你计划使用的端点可以看到你已注资的账户。

从 JavaScript 使用 Sepolia

使用 viem 时，Sepolia 是内置链，因此你只需要提供传输：

import { createPublicClient, http, formatEther } from "viem";
import { sepolia } from "viem/chains";

const client = createPublicClient({
  chain: sepolia,
  transport: http("https://eth-sepolia.api.onfinality.io/public")
});

const block = await client.getBlockNumber();
const balance = await client.getBalance({ address: "0xYourAddress" });

console.log("Sepolia block:", block);
console.log("Balance:", formatEther(balance), "ETH");

使用 ethers 时，模式类似——传入 Sepolia 网络和提供者 URL：

import { JsonRpcProvider, formatEther } from "ethers";

const provider = new JsonRpcProvider(
  "https://eth-sepolia.api.onfinality.io/public",
  11155111
);

console.log(await provider.getBlockNumber());
console.log(formatEther(await provider.getBalance("0xYourAddress")));

两个示例都使用 HTTP。如果你的应用程序依赖 eth_subscribe 获取新区块或待处理日志，则需要 WebSocket 传输，并且你的提供商必须公开它。在设计订阅之前检查传输支持。

调试常见的 Sepolia 故障

下表将你最可能看到的症状映射到通常原因和首先要检查的内容。

其中一些值得更多细节。

测试网上的 nonce 混乱。 因为你可能同时从脚本、钱包和浏览器发送交易，nonce 可能会漂移。当交易似乎卡住时，查询待处理 nonce 而不是最新 nonce，并避免使用猜测值发送替换交易。

日志查询返回空。 eth_getLogs 对区块范围敏感。在繁忙的测试网上，范围太宽可能会被拒绝，而范围太窄则返回空。从部署区块附近的一个适度范围开始，然后扩大。

CI 期间的速率限制。 如果你的管道针对公共端点运行许多并行作业，失败将看起来是随机的。这通常是争用，而不是代码中的错误。API 密钥或专用节点为你提供稳定的预算。

何时从公共端点迁移

公共端点很方便，适合早期开发。它们在以下情况下成为负担：

• 你的 CI 管道在每次提交时运行并产生突发流量。
• 索引器或后端服务持续轮询。
• 你需要归档状态进行历史查询。
• 你依赖 WebSocket 订阅进行实时更新。
• 你需要在发布前出现问题时获得支持渠道。

此时，根据实际影响工作负载的标准比较提供商：方法覆盖、归档可用性、传输支持、限制如何执行以及故障转移如何工作。RPC 定价 和 支持的 RPC 网络 列表是很好的起点，提供商选择指南 详细介绍了评估过程。

关键要点

• Sepolia 使用链 ID 11155111，在 JSON-RPC 响应中为 0xaa36a7。
• 在调试其他任何内容之前，始终验证 eth_chainId——指向主网是一个常见错误。
• 水龙头为测试账户提供资金；没有支持的路径将主网 ETH 桥接到 Sepolia。
• 公共端点适合轻量开发；CI、索引器和基于订阅的应用程序受益于托管或专用容量。
• 大多数 Sepolia 错误属于一小部分：错误的链、没有资金、nonce 漂移、速率限制或不支持的方法。

常见问题解答

什么是 Sepolia RPC URL？

没有单一的规范 URL——Sepolia 是一个网络，多个提供商为其公开端点。对于轻量测试，你可以使用公共 OnFinality 端点 https://eth-sepolia.api.onfinality.io/public。对于类似生产的工作负载，请使用 API 密钥端点或专用节点。

什么是 Sepolia 链 ID？

Sepolia 的链 ID 是 11155111。JSON-RPC 将其作为十六进制字符串 0xaa36a7 返回。

Sepolia 与以太坊主网相同吗？

不。Sepolia 是一个独立的测试网，有自己的状态和自己的 ETH，没有货币价值。它运行相同的 EVM 和 JSON-RPC 接口，这就是为什么主网工具通常只需更改配置即可工作。

为什么我的 Sepolia 交易说资金不足？

你的账户没有足够的 Sepolia ETH 来支付交易价值和 gas。从水龙头请求测试 ETH，然后在重试之前确认区块浏览器上的余额。

我可以在 Sepolia 上使用 WebSocket 订阅吗？

只有当你的提供商公开 WebSocket 传输时。HTTP 端点不支持 eth_subscribe。在围绕实时订阅构建之前，检查你选择的端点的传输支持。

我需要为 Sepolia 使用归档节点吗？

只有当你查询旧区块高度的历史状态时。最近状态查询在标准节点上工作。如果你的应用程序需要历史余额或跟踪，请与你的提供商确认归档可用性。