Base RPC MetaMask 设置：链 ID、RPC URL 与连接修复

添加自定义网络时 MetaMask 会做什么

在 MetaMask 中添加自定义网络时，钱包会存储五个字段：NetworkName、RPC URL、Chain ID、Currency Symbol 和 Block Explorer URL。这些不仅仅是标签。RPC URL 是 MetaMask 用于所有 JSON-RPC 请求的 HTTP 端点，而 Chain ID 是 MetaMask 期望该端点报告的值。根据 MetaMask 支持文档，钱包会在保存网络之前验证连接。

验证步骤是一次 JSON-RPC 调用。MetaMask 向 RPC URL 发送 eth_chainId，并将返回的十六进制链 ID 与你输入的十进制值进行比较。它通常还会调用 net_version 作为二次检查。如果任一调用失败、超时或返回不匹配的链 ID，MetaMask 会中止保存并显示错误。以太坊 JSON-RPC 规范将 eth_chainId 定义为返回当前网络链 ID 的方法，这就是钱包依赖它进行网络检测的原因。

这意味着 RPC URL 必须能从浏览器上下文访问，必须支持 JSON-RPC 2.0，并且必须返回你输入的链 ID。在终端中可用但阻止浏览器来源的 URL 在 MetaMask 中仍会失败。返回其他网络有效链 ID 的 URL 也会失败。钱包并不是在测试端点是否快速或可靠；它是在测试端点是否是你声称的网络。

• NetworkName：本地存储的标签，不会发送到 RPC 端点。
• RPC URL：所有 JSON-RPC 调用的 HTTP 端点。
• Chain ID：MetaMask 期望 eth_chainId 以十六进制返回的十进制值。
• Currency Symbol：仅用于显示；不影响 RPC 调用。
• Block Explorer URL：用于链接交易，不用于验证。

主网和 Sepolia 的正确 Base 网络参数

Base 主网使用链 ID 8453，即十六进制的 0x2105。原生货币是 ETH。Base Sepolia（测试网）使用链 ID 84532，即十六进制的 0x14a34。这些值记录在 Base 文档中。链 ID 必须完全匹配，因为 MetaMask 会将你输入的十进制值与 eth_chainId 返回的十六进制值进行比较。

对于 RPC URL，你可以使用公共端点或提供商端点。公共端点便于轻量交互使用，但它们是共享的，且通常有速率限制。提供商端点，例如 Base RPC 端点（RPC Assistant） 页面中描述的端点，专为更高的请求量设计，并可能包含 WebSocket 支持。如果你需要 WebSocket 传输，请参阅 Base RPC WebSocket 连接指南。

区块浏览器 URL 是可选的，但很有用。对于 Base 主网，浏览器通常是 https://basescan.org。对于 Base Sepolia，它是 https://sepolia.basescan.org。这些不影响 RPC 验证，但能让交易链接正常工作。

• Base 主网：链 ID 8453（0x2105），货币 ETH，RPC URL 来自提供商或公共端点。
• Base Sepolia：链 ID 84532（0x14a34），货币 ETH，RPC URL 来自提供商或公共端点。
• 主网区块浏览器：https://basescan.org
• Sepolia 区块浏览器：https://sepolia.basescan.org

五类连接错误及其根本原因

大多数 Base 到 MetaMask 的连接失败可归为五类。第一类是“无法获取链 ID”。当 RPC URL 错误、失效或被限制时会发生这种情况。端点可能离线、需要 API 密钥，或者在到达 JSON-RPC 层之前就拒绝请求。MetaMask 无法继续，因为它无法确认链。

第二类是链 ID 不匹配。钱包显示一条链，但端点返回另一条。当你粘贴其他网络（如以太坊主网或测试网）的 RPC URL，同时输入 Base 的链 ID 时，就会发生这种情况。MetaMask 将返回的十六进制链 ID 与你输入的十进制值进行比较，如果不同则拒绝保存。

第三类是 CORS 或来源阻止。基于浏览器的钱包从 Web 来源调用 RPC URL。如果端点未包含适当的 Access-Control-Allow-Origin 头，浏览器会在 MetaMask 读取响应之前阻止它。这在钱包中通常看起来像通用网络错误，但浏览器控制台会显示 CORS 失败。

第四类是 HTTP 429 速率限制。公共端点会强制执行请求配额。MetaMask 会频繁轮询 RPC URL，尤其是在钱包打开并跟踪待处理交易时。对偶尔调用的 dapp 可用的公共端点，在钱包轮询下仍可能返回 429。Base RPC 速率限制与可靠性文章更详细地介绍了配额行为。

第五类是返回 HTML 错误页面或代理插页而非 JSON。当代理、强制门户或配置错误的网关拦截请求并返回 HTML 时，就会发生这种情况。MetaMask 期望 JSON-RPC 2.0 响应，无法解析 HTML，因此报告获取失败。解决方法是验证端点返回带有正确 Content-Type 头的 JSON。

• 无法获取链 ID：RPC URL 错误、失效或被限制。
• 链 ID 不匹配：端点返回的链 ID 与输入的不同。
• CORS/来源阻止：端点不允许浏览器来源。
• HTTP 429：公共端点在钱包轮询下受到速率限制。
• HTML 而非 JSON：代理或网关插页破坏解析。

使用 curl 独立测试端点

在更改 MetaMask 中的任何内容之前，先在钱包外部测试 RPC URL。使用 eth_chainId 向端点发送一次 curl POST，就能告诉你端点是否可达以及返回什么链 ID。对于 Base 主网，结果应为 0x2105。如果你得到 HTTP 错误、HTML 正文或其他十六进制值，问题出在端点，而不是 MetaMask。

JSON-RPC 2.0 规范要求 jsonrpc 字段设置为 "2.0"，以及 method、params 和 id。以下 curl 命令发送一个最小请求。将 URL 替换为你的候选 Base 端点。-i 标志会包含响应头，以便你检查 Content-Type 和任何 CORS 头。

• 预期的 Base 主网结果：{"jsonrpc":"2.0","id":1,"result":"0x2105"}
• 预期的 Base Sepolia 结果：{"jsonrpc":"2.0","id":1,"result":"0x14a34"}
• 检查 HTTP 状态：预期为 200；401、403 或 429 表示访问或配额问题。
• 检查 Content-Type：application/json；text/html 表示代理或错误页面。

curl -i -X POST https://mainnet.base.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

使用浏览器控制台 Fetch 暴露 CORS 失败

CORS 失败在 curl 中不可见，因为 curl 不强制执行浏览器来源策略。要重现 MetaMask 看到的情况，请在任何页面上打开浏览器控制台，并对候选 RPC URL 运行 fetch。如果端点不允许你的来源，浏览器将阻止响应并记录 CORS 错误。这与 MetaMask 从扩展上下文调用端点时遇到的失败相同。

以下代码片段从浏览器发送相同的 eth_chainId 请求。如果成功，你将看到 JSON 响应。如果失败，控制台将显示 CORS 或网络错误。此测试可区分在服务器端可用的端点与在浏览器钱包中可用的端点。

• 如果控制台显示 CORS 错误，则端点不允许你的浏览器来源。
• 如果控制台显示网络错误，则端点可能不可达或被扩展阻止。
• 如果控制台显示 JSON 解析错误，则端点返回了 HTML 或非 JSON 内容。

fetch('https://mainnet.base.org', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_chainId',
    params: []
  })
})
  .then(res => res.json())
  .then(data => console.log('Chain ID:', data.result))
  .catch(err => console.error('Fetch failed:', err));

可运行的 Node.js 探测：eth_chainId、net_version 和 eth_blockNumber

更彻底的探测会检查三个方法：eth_chainId、net_version 和 eth_blockNumber。这会给你链 ID、网络 ID 和最新区块号。下面的脚本为每个方法打印 PASS 或 FAIL，以及 HTTP 状态和响应正文的前几个字节。它使用 Node.js 18 及更高版本中内置的 fetch API。

使用 node probe.js https://your-base-endpoint 运行此脚本。将 URL 参数替换为你的候选端点。如果任何检查失败，脚本将以非零代码退出，这使其可用于 CI 或快速终端检查。

• 对于 Base 主网，eth_chainId 应返回 0x2105。
• 对于 Base 主网，net_version 应返回 8453。
• eth_blockNumber 应返回随时间增加的十六进制区块号。
• 任何 FAIL 都表明该端点不适合 MetaMask。

const url = process.argv[2];
if (!url) {
  console.error('Usage: node probe.js <RPC_URL>');
  process.exit(1);
}

const methods = ['eth_chainId', 'net_version', 'eth_blockNumber'];

async function probe(method) {
  const body = JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method,
    params: []
  });
  try {
    const res = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body
    });
    const text = await res.text();
    const firstBytes = text.slice(0, 80).replace(/\n/g, ' ');
    let parsed;
    try {
      parsed = JSON.parse(text);
    } catch (e) {
      console.log(`FAIL ${method} | HTTP ${res.status} | non-JSON body: ${firstBytes}`);
      return false;
    }
    if (parsed.error) {
      console.log(`FAIL ${method} | HTTP ${res.status} | error: ${JSON.stringify(parsed.error)}`);
      return false;
    }
    console.log(`PASS ${method} | HTTP ${res.status} | result: ${parsed.result}`);
    return true;
  } catch (err) {
    console.log(`FAIL ${method} | network error: ${err.message}`);
    return false;
  }
}

(async () => {
  let allPass = true;
  for (const method of methods) {
    const ok = await probe(method);
    if (!ok) allPass = false;
  }
  process.exit(allPass ? 0 : 1);
})();

为你自己的端点建立可复现的结果表

使用下表记录你自己的测量结果。为你测试的每个端点填写一行。目标是客观比较端点并确定适用哪类错误。不要依赖记忆；记录 HTTP 状态、返回的链 ID、CORS 是否通过以及你应用的修复。

如果你正在测试多个端点，请为每个端点运行 Node.js 探测和浏览器 fetch。该表可以清楚地显示哪个端点适合 MetaMask，哪个需要不同的方法，例如提供商端点或 WebSocket 连接。

• Endpoint：你测试的完整 RPC URL。
• HTTP status：探测返回的状态码。
• eth_chainId：返回的十六进制值或错误消息。
• CORS ok?：如果浏览器 fetch 成功则为 yes，失败则为 no。
• Error class：上述五类之一。
• Fix applied：你所做的更改，例如切换端点或删除并重新添加网络。

为什么 MetaMask 会缓存损坏的网络条目

MetaMask 在本地存储自定义网络配置。如果你添加了带有损坏 RPC URL 的网络，即使你在其他地方更正了 URL，钱包也可能保留该条目。在某些情况下，修复需要完全删除网络并使用正确的参数重新添加。MetaMask 支持文档中记录了此行为。

缓存行为意味着就地编辑 RPC URL 可能不够。如果你在更改 URL 后看到持续错误，请从 MetaMask 的网络列表中删除该网络并重新添加。这会强制钱包针对新端点重新运行 eth_chainId 验证。

这也是为什么以前可用的网络会突然失败。如果端点更改了 CORS 策略或开始限速，MetaMask 可能仍缓存旧配置。删除并重新添加网络是重置验证状态的最干净方法。

• MetaMask 在本地存储自定义网络，可能不会自动刷新验证。
• 如果编辑 RPC URL 后错误仍然存在，请删除并重新添加网络。
• 重新添加会强制针对新端点进行全新的 eth_chainId 调用。

客户端修复和公共端点的局限性

任何客户端修复都无法替代可靠的端点。如果你将公共 Base 端点用于轻量交互之外的任何用途，最终会遇到速率限制或 CORS 限制。MetaMask 会频繁轮询 RPC URL，对偶尔调用的 dapp 可用的公共端点，在钱包轮询下仍可能返回 429。Base RPC 速率限制与可靠性文章解释了配额机制。

对于生产应用程序，请使用具有文档化服务级别的提供商端点。RPC 定价页面描述了可用计划，API 服务页面涵盖了更广泛的 API 产品。如果你需要用于订阅的 WebSocket 传输，Base RPC WebSocket 连接指南涵盖了该设置。

另一个限制是 MetaMask 的验证仅检查 eth_chainId 和 net_version。它不测试 eth_blockNumber 或验证端点是否已同步。端点可以通过验证但仍返回过时的区块数据。对于依赖最终性的应用程序，请参阅 Base 最终性：安全区块和已最终确定区块文章。

• 公共端点是共享的且有限速；不适合高频轮询。
• MetaMask 验证不测试区块高度或同步状态。
• 对于生产使用，建议使用具有文档化 SLA 的提供商端点。
• WebSocket 传输需要单独的端点和配置。

持续连接失败的故障排查清单

如果你已使用 curl 和浏览器 fetch 测试了端点，但 MetaMask 仍然失败，请按此清单逐项排查。首先确认你输入的链 ID 与 eth_chainId 返回的十六进制值匹配。对于 Base 主网，十进制值为 8453，十六进制值为 0x2105。对于 Base Sepolia，十进制值为 84532，十六进制值为 0x14a34。

接下来，检查端点是否需要 API 密钥。某些提供商端点在无密钥时返回 401 或 403。如果你使用的是公共端点，请检查它是否有速率限制以及你是否触发了限制。如果浏览器控制台显示 CORS 错误，则端点不允许你的来源；请切换到支持浏览器来源的提供商端点。

如果端点返回 HTML 而非 JSON，你可能位于代理或强制门户之后。尝试从其他网络访问端点或禁用任何代理扩展。最后，如果其他方法都不起作用，请从 MetaMask 中删除网络并使用正确的参数重新添加。有关链 ID 获取错误的相关演练，请参阅 Base RPC 超时与重试模式。

• 验证链 ID：Base 主网为 8453（0x2105），Base Sepolia 为 84532（0x14a34）。
• 检查 API 密钥要求：401 或 403 表示端点受限。
• 检查速率限制：429 表示配额耗尽。
• 检查 CORS：浏览器控制台错误表示来源限制。
• 检查 HTML 响应：代理或强制门户可能正在拦截。
• 如果修复端点后错误仍然存在，请删除并重新添加网络。

下一步：选择可靠的 Base RPC 端点

一旦你确认了正确的链 ID 并测试了端点，下一步就是选择与你的使用情况匹配的端点。对于轻量交互使用，公共端点可能就足够了。对于涉及频繁轮询、自动交易或生产 dapp 的任何情况，提供商端点是更好的选择。Base RPC 端点（RPC Assistant）页面可帮助你比较选项。

如果你正在 Base 上构建并需要 HTTP 和 WebSocket 访问，请查看 Base RPC WebSocket 连接指南。有关速率限制规划，请参阅 Base RPC 速率限制与可靠性。有关最终性考虑，请参阅 Base 最终性：安全区块和已最终确定区块。

有关 RPC 主题的更广泛概述，请访问 OnFinality Learn 中心。如果你准备从公共端点迁移到托管服务，RPC 定价和 API 服务页面描述了可用选项。关键要点是，MetaMask 验证只是起点，而不是可靠性的保证；请选择与你的请求量和传输需求匹配的端点。

• 公共端点仅用于轻量交互使用。
• 生产、自动化或高频轮询请使用提供商端点。
• 如果需要订阅，请考虑 WebSocket 传输。
• 如果你的应用程序依赖区块确认，请查看最终性文档。