NEAR链注入式 Provider API 完全指南：DApp 钱包集成的最优实践

关键词：注入式 Provider API、NEAR 协议、DApp 钱包集成、DEX API、链上交易、签名交互、账户授权

什么是 NEAR 注入式 Provider API？

注入式 Provider API 是 NEAR 生态中无需手动安装 SDK 的一种极简集成交互方案。当用户通过支持该 API 的钱包访问 DApp 时，钱包浏览器扩展会自动在页面内部植入 window.okxwallet.near 对象，开发者即可通过 JavaScript 直接调用链上读写、签名等功能，实现一键连接钱包、即席交易的顺滑体验。

核心优势：

无额外依赖，最快 3 行代码接入；
完全兼容 NEAR 官方 RPC 与链上合约 ABI；
支持批量交易、消息签名、账户枚举等高频场景。

注入对象快速入口

开发者在代码中通过以下两种方式即可拿到全局 NEAR 实例：

推荐：window.okxwallet.near
兼容性写法：window.near

⚠️ 使用 TypeScript 时，别忘了为全局对象声明 @types/near-api-js 或自行拓展 Window 接口，防止编辑器报错。

如何连接 OKX Extension 钱包

1. 请求登录：`requestSignIn()`

DApp 最常用的是引导用户完成登录与授权，可细分两种粒度：

仅获取账户 ID（无合约调用权限）

调用后弹窗只要求用户确认链上地址，返回最小权限对象：

const myNear = window.okxwallet.near;
const { accountId } = await myNear.requestSignIn();
console.log("当前已登录账户：", accountId);

同步获取 AccessKey（带合约交互权限）

若后续要读写指定合约，需在调用时指定：

contractId：目标合约地址
methodNames：允许调用的 view / change 方法列表
返回对象除了 accountId 外，还会携带 publicKey 与 accessKey。

示例：

const { accountId, publicKey, accessKey } = await myNear.requestSignIn({
  contractId: "token.near",
  methodNames: ["ft_balance_of", "ft_transfer"]
});

2. 主动退出：`signOut()`

钱包授权并未占用浏览器 Cookie，但用户数据仍短暂缓存在内存。调用 signOut() 会触发钱包端断开，并清空本地存储的会话：

await myNear.signOut();

任何异常断开（用户手动关闭插件、切换账户）也会自动触发该事件。

3. 快速状态检测

isSignedIn()：布尔值，返回当前页面是否已登录；
getAccountId()：若已登录，直接返回链上地址，未登录则返回 null。

链下消息签名：`signMessage()`

需要链下登录验证或生成个性化签名的场景，可调用：

const message = "user_login_1686739547";
const { signature, publicKey } = await myNear.signMessage({ message });

签名后为 64 字节十六进制字符串，前端即可将 signature 与 publicKey 带到服务器做 ECDSA 验证。

合约交互三板斧

单笔交易：`signAndSendTransaction()`

当用户需要在链上执行单次转账或调用方法时，只需传入：

const tx = await myNear.signAndSendTransaction({
  receiverId: "game.near",
  actions: [{
    type: "FunctionCall",
    params: {
      methodName: "play",
      args: { round: 3 },
      gas: "30000000000000",
      deposit: "10000000000000000000000" // 0.01 NEAR
    }
  }]
});

返回值里包含 transaction_outcome.transaction.hash，DApp 可用该 txHash 在接收端轮询结果即可。
👉 三分钟锁定交易精准广播技巧，点此掌握！

批量交易：`requestSignTransactions()`

复杂场景往往需将授权、转账、方法调用等打包到一个区块里，节省 Gas。例如：

const txs = await myNear.requestSignTransactions({
  transactions: [
    { receiverId: "app.near", actions: [...] },
    { receiverId: "token.near", actions: [...] }
  ]
});

⚠️ 该 API 只负责链下签名，并未自动广播。开发者需拿到返回的 SignedTransaction[]，通过 RPC 再手动发送。

事件监听：实时感知钱包状态变化

事件名	触发场景
`signIn`	用户授权成功后
`signOut`	用户主动或被动退出
`accountChanged`	钱包内切换子账户，地址立即变动

代码示例：

myNear.on("accountChanged", (newAccountId) => {
  location.reload(); // 或刷新余额、重连子图表
});

常见问题与解答（FAQ）

Q1：为什么有时拿不到 window.okxwallet？
A：90% 场景是用户没安装对应扩展；其余可能是浏览器隐私模式或内容安全策略屏蔽脚本注入。引导用户检查插件状态并刷新页面即可。

Q2：requestSignTransactions() 报 “Batch size exceed” 怎么办？
A：NEAR 主网单区块最多 256 KiB，建议将批量交易拆分为多笔或合并逻辑以减少 Actions。例如把 5 次 ft_transfer 整合成一次 ft_batch_transfer。

Q3：如何判断交易是否真正打包进区块？
A：使用返回的 txHash 轮询 EXPERIMENTAL_tx_status，如果 status 内字段变为 SuccessValue 即为成功；若 Failure，DApp 需回滚本地状态并提示用户。

Q4：链上合约升级导致方法签名变化，旧 DApp 会崩溃吗？
A：不会。注入式 API 是裸签名调用，升级后只需同步修改 methodName 或 args 即可，无需重新安装钱包组件。

Q5：个人开发者如何本地调试？
A：启用 TestNet，使用同一套 API 仅替换 explorerUrl：https://explorer.testnet.near.org。👉 一键切换至测试网络的快捷教程在这里！

写在最后

IMWeb3 时代，NEAR 注入式 Provider API 的零门槛接入，正在让钱包集成从“数日开发”缩短到“即插即用”。掌握 requestSignIn、signAndSendTransaction 及事件总线三板斧，你就可以在最短时间内为用户打造出丝滑链上体验。对于尚未配置环境的新团队，建议先跑通上述最简 Demo，逐步叠加业务复杂性，才能真正发挥高速低费链的性能红利。