TypeScript SDK：Aptos 客户端

目的

指导如何在 @aptos-labs/ts-sdk 中创建和配置 Aptos 客户端及 AptosConfig。单个客户端实例用于所有读/写操作以及账户/交易相关 API。

务必遵守

1. 每个应用仅创建一个 Aptos 实例（单例模式），并重复使用——避免对同一网络多次调用 new Aptos(config)。
2. 通过 AptosConfig 配置网络——使用 Network.TESTNET 或 Network.MAINNET（或自定义端点）。
3. 生产环境中使用环境变量配置网络/URL——例如 process.env.APTOS_NETWORK 或 import.meta.env.VITE_APP_NETWORK。
4. 开发时默认使用 Network.TESTNET——Devnet 会频繁重置。

切勿执行

1. 不要为每次请求新建 Aptos 客户端——请复用单例实例。
2. 在使用公共网络时，禁止在源码中硬编码全节点（fullnode）/索引器（indexer）URL——应使用 Network 枚举。
3. 使用自定义端点时，不可省略 network 配置项——v5.2+ 版本中需配合自定义 URL 显式指定 Network.CUSTOM。

基础配置

import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

const config = new AptosConfig({ network: Network.TESTNET });
const aptos = new Aptos(config);

网络选项

// 预定义网络
const devnet = new AptosConfig({ network: Network.DEVNET });
const testnet = new AptosConfig({ network: Network.TESTNET });
const mainnet = new AptosConfig({ network: Network.MAINNET });

// 自定义端点（v5.2+ 起必须指定 network）
const custom = new AptosConfig({
  network: Network.CUSTOM,
  fullnode: "https://your-fullnode.example.com/v1",
  indexer: "https://your-indexer.example.com/v1/graphql",
  faucet: "https://your-faucet.example.com"
});

单例模式（推荐）

// lib/aptos.ts 或类似路径
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

function getNetwork(): Network {
  const raw = typeof process !== "undefined" ? process.env.APTOS_NETWORK : import.meta.env?.VITE_APP_NETWORK;
  switch (raw) {
    case "mainnet":
      return Network.MAINNET;
    case "devnet":
      return Network.DEVNET;
    default:
      return Network.TESTNET;
  }
}

const config = new AptosConfig({ network: getNetwork() });
export const aptos = new Aptos(config);

可选端点（按服务覆盖默认值）

const config = new AptosConfig({
  network: Network.TESTNET,
  fullnode: "https://fullnode.testnet.aptoslabs.com/v1", // 覆盖默认全节点地址
  indexer: "https://indexer.testnet.aptoslabs.com/v1/graphql",
  faucet: "https://faucet.testnet.aptoslabs.com",
  pepper: "https://...", // 无密钥 Pepper 服务
  prover: "https://..." // 无密钥 Prover 服务
});
const aptos = new Aptos(config);

客户端配置（HTTP、超时、Bun）

// 使用 Bun 时禁用 HTTP/2（推荐）
const config = new AptosConfig({
  network: Network.TESTNET,
  clientConfig: { http2: false }
});
const aptos = new Aptos(config);

客户端使用方式

构造完成后，使用同一个 aptos 实例调用以下功能：

• 账户 / 余额：aptos.getAccountInfo()、aptos.getBalance()、aptos.getAccountResources() 等。
• 交易：aptos.transaction.build.simple()、aptos.signAndSubmitTransaction()、aptos.waitForTransaction()。
• 视图调用（View）：aptos.view()。
• 水龙头（Faucet）：aptos.fundAccount()（仅限 Devnet/Testnet）。
• 代币 / 数字资产 / 对象 / ANS / 质押：aptos.coin.*、aptos.digitalAsset.*、aptos.fungibleAsset.*、aptos.object.*、aptos.ans.*、aptos.staking.*。

常见错误

参考资料

• SDK 源码：src/api/aptos.ts、src/api/aptosConfig.ts
• 设计模式文档：TYPESCRIPT_SDK.md
• 相关模块：ts-sdk-account、ts-sdk-transactions、ts-sdk-wallet-adapter、use-ts-sdk