@solana/web3-compat

@solana/web3-compat 是连接长期运行的 @solana/web3.js 应用与新版 Kit 运行时的桥梁。只需更换 import，保留你应用已熟悉的接口，即可逐步采用 Kit 的新特性，无需一次性重写所有辅助函数或指令。

与 Kit 相关依赖一起安装

$ 
npm install @solana/web3-compat @solana/kit @solana/clientCopy

该兼容层会重新导出经典的 Web3 类型（Connection、PublicKey、Transaction 等），但内部会委托给 Kit 的网络和编解码模块。你可以继续使用现有的 RPC 端点，同时享受 Kit 更可预测的区块哈希处理和钱包抽象带来的优势。

替换 import（无需其他代码更改）

大多数项目只需切换 import 源即可逐文件迁移。命名导入和命名空间导入都与旧包保持一致。

import { Connection, PublicKey } from "@solana/web3.js";

import { Connection, PublicKey } from "@solana/web3-compat";

CommonJS 也同样适用：

const solanaWeb3 = require("@solana/web3-compat");
const connection = new solanaWeb3.Connection("https://api.devnet.solana.com");

在底层，Connection 会将读写操作转发到 @solana/client，因此像 sendAndConfirmTransaction、simulateTransaction 和 getProgramAccounts 这样的辅助工具也能在不影响业务逻辑的前提下，受益于新版运行时。

需要 Kit 类型时桥接辅助工具

当你直接采用 Kit（比如在新组件中使用 @solana/client 或 @solana/react-hooks）时，可以使用 compat 包中提供的桥接辅助工具，在两个生态之间进行类型转换：

import {
  PublicKey,
  toAddress,
  toPublicKey,
  toWeb3Instruction,
  toKitSigner
} from "@solana/web3-compat";

const legacyKey = new PublicKey("11111111111111111111111111111111");
const kitAddress = toAddress(legacyKey);
const backToWeb3 = toPublicKey(kitAddress);

混合运行时变得安全：新版 hooks 可以生成 Kit 指令，然后 toWeb3Instruction 会将其包装，适配旧流程，直到整个项目全部迁移完成。

渐进式迁移模式

• 增量发布：一次只更新一个功能文件夹。当某个模块不再需要 compat 时，直接指向 @solana/client/@solana/react-hooks，无需修改其他部分。
• 共享 RPC 调优：由于 compat 依赖 Kit 连接，承诺级别、优先级费用或 RPC URL 的调整都通过一个配置对象统一管理。
• SPL + 交易助手：目前可以保留旧版交易构建器，但准备好后可以使用 client.helpers.transaction.prepare。compat 依然可以提交相同的已签名负载。
• 测试：可以复用现有的 Web3 mock，因为公共接口保持不变，但在测试中你可以 stub Kit 客户端，实现更丰富的模拟。

第 0 阶段发布内容

• Connection 及 getLatestBlockhash、getBalance、getAccountInfo、 getProgramAccounts、getSignatureStatuses、sendRawTransaction、 confirmTransaction 和 simulateTransaction。
• 实用工具如 LAMPORTS_PER_SOL、sendAndConfirmTransaction 和 compileFromCompat。
• SystemProgram.transfer 以及所有核心 Web3 基础组件（Keypair、 Transaction、VersionedTransaction、TransactionInstruction）。

在准备好基于同一 Kit 运行时构建新 UI 时，请结合本指南与 @solana/client 概览 以及 @solana/react-hooks 指南 一起使用。