near-api-js连接Pagoda测试网RPC携带自定义头触发CORS报错

问题场景 #

• 尝试通过near-api-js接入Pagoda服务，初始化核心代码如下：

const CONTRACT_NAME = process.env.CONTRACT_NAME || 'mycontract.testnet'
const API_KEY = '06cffba5-e0c5-bla-bla-blablabla';
const keyStore = new keyStores.BrowserLocalStorageKeyStore();

• 使用的NEAR测试网连接配置如下：

{
  networkId: 'testnet',
  nodeUrl: 'https://rpc.testnet.near.org/',
  keyStore,
  contractName: CONTRACT_NAME,
  walletUrl: 'https://wallet.testnet.near.org',
  helperUrl: 'https://helper.testnet.near.org',
  explorerUrl: 'https://explorer.testnet.near.org',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json'
  },
}

• 异常表现：移除配置中的headers字段时连接可正常运行；携带包含Pagoda认证所需x-api-key的headers配置时，触发CORS跨域报错，报错信息如下：

Access to fetch at 'https://rpc.testnet.near.org/' from origin 'http://localhost:3000' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: It does not have HTTP ok status.

根因说明 #

你当前配置里填的nodeUrl是NEAR官方提供的公共无认证测试网RPC端点，该端点本身不需要API Key鉴权，也没有配置针对自定义请求头的CORS响应规则。
x-api-key不属于浏览器CORS规范里的安全列表请求头，只要请求携带该头，浏览器会自动在正式请求前发送OPTIONS方法的预检请求，校验服务端是否允许当前源、当前请求头的跨域请求。公共RPC端点对这类带自定义头的预检请求不会返回符合CORS要求的响应，甚至直接返回非200状态码，就会触发你看到的跨域拦截。

可行解决方案 #

• 替换nodeUrl为Pagoda分配的专属RPC端点：Pagoda为接入用户提供的专属RPC端点本身已经和你的账户、API Key做了绑定，直接请求该端点即可完成鉴权，不需要额外在请求头中携带x-api-key，也就不会触发自定义头带来的预检CORS问题。
• 本地开发调试可配置开发服务代理：如果临时调试不想更换端点，可以在本地前端开发服务（比如webpack dev server、vite dev server）中配置代理规则，将前端发往同源路径下的RPC请求转发到官方RPC地址，代理是服务端到服务端的请求，不存在浏览器CORS限制，转发时再注入x-api-key请求头即可。示例逻辑：将nodeUrl改为本地同源路径/near-rpc，开发服务把所有/near-rpc开头的请求转发到https://rpc.testnet.near.org/，转发时补上x-api-key头。
• 正式环境不要在前端直接暴露API Key：浏览器端的所有代码、配置用户都可以直接抓取获取，正式环境建议所有涉及Pagoda RPC的请求都走自有服务端代理，避免API Key泄露被盗刷额度。

内容的提问来源于stack exchange，提问作者howdyho