如何使用类似 Chainlist 的目录来查找支持的 RPC 网络和端点？

类似 Chainlist 的目录是一个查找表，用于解决开发者经常需要的两件事：网络的链 ID 以及一个或多个为该链提供 JSON-RPC 服务的 RPC 端点。当你向 MetaMask 添加自定义网络、配置 viem 客户端或将后端索引器指向新链时，你实际上是在问“这个链的 ID 是什么，以及我该调用哪个 URL？”目录在浏览器中回答这个问题，而不是在分散的文档中。

本页解释了这些目录的组织方式、如何读取它们公开的元数据、如何在依赖端点之前验证它，以及何时公共目录条目不再是完成任务的正确工具。

快速建议：目录条目 vs 托管端点

当你探索链、测试钱包集成或编写一次性脚本时，使用公共目录条目。当端点位于真实用户依赖的请求路径上时，使用托管的 RPC API 或专用节点。

分界线不是“主网 vs 测试网”——而是失败的请求是否会破坏用户关心的事情。如果连接断开意味着付费用户的交易失败，那么目录列表就是错误的抽象。

如果你已经过了探索阶段，请跳转到支持的 RPC 网络查看通过托管端点可用的链，以及RPC 定价了解使用量如何计量。

类似 Chainlist 的目录实际存储什么

目录条目是结构化的元数据，而不仅仅是 URL。对集成重要的字段在大多数目录中是一致的，因为它们映射到钱包已经理解的 EIP-3085 wallet_addEthereumChain 参数。

目录的质量取决于其最后一次更新。端点会退役、速率限制会变化、链会分叉。将任何列表视为验证的起点，而不是保证。

在信任端点之前如何验证它

验证是一系列简短的 JSON-RPC 调用。在你从目录中提取任何端点并将其接入应用之前，请对其运行这些调用。

# 1. 确认链 ID 与目录声称的一致
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

# 2. 通过将区块高度与已知来源比较，确认节点已同步
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 3. 确认你实际需要的方法受支持
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{"fromBlock":"latest","toBlock":"latest"}]}'

第 3 步是人们会跳过的。一个端点可以返回有效的 eth_chainId，但仍然拒绝 eth_getLogs、debug_traceTransaction 或归档查询。测试你的应用调用的确切方法，而不仅仅是握手。

如果你配置的是钱包而不是后端，相同的数据会进入网络配置对象：

await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x38',
    chainName: 'BNB Smart Chain Mainnet',
    nativeCurrency: { name: 'BNB Chain Native Token', symbol: 'BNB', decimals: 18 },
    rpcUrls: ['https://bnb.api.onfinality.io/public'],
    blockExplorerUrls: ['https://bscscan.com'],
  }],
});

保持链 ID、符号、小数位数和浏览器 URL 与你验证的来源一致。混合来自两个不同目录的值是“错误网络”错误的常见原因。

正确读取目录条目

当你打开一个列表时，按以下顺序处理：

1. 首先匹配链 ID。 名称有歧义——多个网络共享相似的名称。数字 ID 是真相的来源。
2. 检查端点传输方式。 有些条目仅支持 HTTP，有些公开 WebSocket，有些两者都支持。如果你的应用需要实时订阅，请在提交之前确认 ws 支持。
3. 注意列出了多少个端点。 单个端点是单点故障。如果目录列出了多个，这暗示维护者期望轮换。
4. 检查浏览器链接。 当交易行为异常时，可用的浏览器是你最快的调试工具。
5. 寻找测试网对应项。 如果你正在构建，你需要一个具有相同结构的测试网条目，以便排练部署。

对于需要跨环境稳定端点的链，OnFinality 通过相同的 API 表面公开主网和测试网端点，因此你的客户端代码在它们之间不会改变。请参阅 BNB Chain 和 BNB Chain Testnet 作为这种配对的示例。

当列出的端点失败时

公共端点以可预测的方式失败。在开始更改代码之前，将症状与原因匹配。

其中大多数不是你的代码中的错误。它们表明共享公共端点被要求执行生产工作。修复通常是将该流量移动到具有定义容量和支持路径的端点。

公共目录 vs 托管 RPC API vs 专用节点

这三个选项位于从“免费和共享”到“隔离并为你运营”的范围内。正确的选择取决于你的产品有多少依赖于该端点。

OnFinality 同时提供托管的 RPC API 服务 和 专用节点，因此你可以从共享基础设施开始，并随着负载增长将特定链迁移到隔离节点。提供商选择指南更详细地介绍了评估标准。

实用的迁移路径

你不必一次性迁移所有内容。分阶段的方法可以保持低风险：

1. 清点。 列出你的应用触及的每个链及其调用的方法。注意哪些需要归档数据、跟踪或 WebSocket。
2. 分类。 将每个链标记为“探索”、“生产读取”或“生产写入”。只有后两者需要托管基础设施。
3. 试点一个链。 将单个生产链迁移到托管端点，保留公共端点作为后备，并比较一周的错误率。
4. 添加故障转移。 配置辅助端点，以便单个提供商中断不会导致你的应用宕机。
5. 扩展。 一旦试点模式得到验证，迁移剩余的生产链。

保留目录条目作为文档。即使你不再在生产中使用其端点，它对于新开发人员的入职也很有用。

关键要点

• 类似 Chainlist 的目录将链 ID 映射到 RPC 端点以及钱包添加网络所需的元数据。
• 在信任端点之前，始终使用 eth_chainId、eth_blockNumber 以及你的应用调用的特定方法验证它。
• 公共目录端点适用于探索和原型，但它们缺乏生产流量的容量保证。
• 当端点失败时，将症状与原因匹配——大多数失败是容量或方法支持问题，而不是代码错误。
• 当端点位于关键请求路径上时，托管 RPC API 和专用节点为你提供定义的容量、使用可见性和支持路径。
• 在你编写的每个配置中保持链 ID、符号、小数位数和浏览器 URL 一致。

常见问题

类似 Chainlist 的目录与 RPC 提供商相同吗？

不。目录是由各种运营商贡献的端点的参考列表。RPC 提供商运营端点背后的节点，并提供容量、监控和支持。目录帮助你发现端点；提供商帮助你在生产中运行它们。

我可以在生产中使用目录中的公共端点吗？

技术上可以，但有风险。公共端点通常是共享和限速的，没有关于可用性或方法支持的保证。对于任何面向用户的内容，请使用具有定义容量和后备的托管端点。

为什么端点返回有效的链 ID 但在其他调用上失败？

链 ID 是一个几乎任何节点都能回答的廉价调用。像 eth_getLogs、debug_traceTransaction 或归档查询这样的方法需要更多资源，并且可能在共享节点上被禁用或限制。始终测试你的应用实际使用的方法。

如何使用目录数据向钱包添加网络？

使用 wallet_addEthereumChain 方法，并提供目录条目中的链 ID、链名称、原生货币、RPC URL 和浏览器 URL。首先验证链 ID，因为名称可能有歧义。

当列出的端点开始返回 429 错误时我该怎么办？

这通常意味着你遇到了共享速率限制。如果可能，减少突发量，添加后备端点，并考虑将该流量移动到容量定义的托管 RPC API 或专用节点。

OnFinality 是否通过一个 API 支持多个链？

OnFinality 在一系列网络上提供 RPC API 访问。查看支持的 RPC 网络页面获取当前列表，以及RPC 定价了解使用量如何构建。