TronWeb简介：TRON区块链的JavaScript SDK

TronWeb 是用于 TRON 开发的主要 JavaScript SDK — 类似于以太坊上的 ethers.js。它处理 dApp、后端和脚本的地址编码、交易构建、智能合约调用和钱包集成。

本介绍涵盖安装、配置、核心概念以及您的第一次 TRX 代码传输。

何时使用 TronWeb

当您需要时使用TronWeb：

• 构建一个连接到 TronLink 或使用嵌入式密钥的 Web dApp
• 运行发送USDT或触发合约的后端服务
• 部署TRC-20 / Solidity 合约并与之交互
• 订阅事件（通过轮询或扩展）

对于没有 SDK 抽象的纯 HTTP 访问，请参阅 TronGrid API 指南 和 HTTP API 参考。

安装

npm install tronweb

浏览器：通过 webpack/vite 捆绑或从 CDN 加载原型（首选 npm 用于生产）。

基本设置

只读（无私钥）

const TronWeb = require('tronweb');

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  headers: { 'TRON-PRO-API-KEY': 'your-api-key' },
});

从 TronGrid 获取 API 密钥。

使用签名密钥（仅限服务器端）

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  privateKey: process.env.TRON_PRIVATE_KEY,
  headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_KEY },
});

Shasta 测试网

const tronWeb = new TronWeb({
  fullHost: 'https://api.shasta.trongrid.io',
  privateKey: 'your-shasta-test-key',
});

从水龙头获取免费的 Shasta TRX 用于测试 TRC-20 部署。

核心对象

发送 TRX 示例

async function sendTrx(toAddress, amountTrx) {
  const amountSun = tronWeb.toSun(amountTrx);
  const tx = await tronWeb.trx.sendTransaction(toAddress, amountSun);
  return tx;
}

使用验证交易 API 跟踪确认。

TRC-20 互动

const USDT = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';

async function getUsdtBalance(address) {
  const contract = await tronWeb.contract().at(USDT);
  const balance = await contract.balanceOf(address).call();
  return tronWeb.toBigNumber(balance).div(1e6).toString();
}

深入研究：查询 TRC-20 余额 和以编程方式发送 USDT。

TronLink 集成（浏览器）{#tronlink}

async function getTronWeb() {
  if (window.tronLink && window.tronLink.ready) {
    return window.tronLink.tronWeb;
  }
  throw new Error('TronLink not found');
}

用户在钱包弹出窗口中签署交易 - 您的网站永远不会看到私钥。

错误处理

常见故障：

• OUT_OF_ENERGY — 账户需要 TRX 或冻结能量
• REVERT — 智能合约拒绝调用
• 无效地址 — 发送前始终tronWeb.isAddress()

映射到生产应用程序中用户友好的消息。

项目结构提示

• 单独的只读TronWeb实例用于公共查询
• 签名者模块通过 HSM 或 env 密钥在服务器上隔离
• TronGrid通话速率限制；缓存块号
• 使用事件监听器 进行存款检测

安全性{#security}

• 智能合约安全
• 验证所有用户提供的地址
• 切勿记录私钥
• 在主网发送之前尽可能模拟合约调用

TronWeb 与其他 SDK

Python 开发者使用tronpy； Go 团队使用 gotron-sdk。 TronWeb 仍然是浏览器 dApp 和 Node.js 后端记录最多的。根据您的堆栈进行选择 - 跨库传输的概念（地址编码、签名、ABI）。

环境变量和秘密

切勿提交私钥。在生产中使用 git 或云机密管理器中排除的 .env 文件。服务器上的TronWeb实例应使用具有最小余额的专用热钱包——清扫到冷存储。如果日志可能已捕获环境转储，请轮换密钥。

相关指南 {#相关}

• TronGrid API 指南
• 触发智能合约
• TRON HTTP API 参考
• 部署TRC-20TronWeb

常见问题解答

什么是TronWeb？

TronWeb 是用于与 TRON 区块链交互的官方 JavaScript 库——来自 Node.js 或浏览器应用程序的账户、合约、交易和查询。

读取区块链数据需要私钥吗？

不会。余额查询等只读操作可与公共全节点或TronGrid API 密钥配合使用，而无需暴露私钥。

TronWeb vs TronGrid？

TronGrid 是托管 API 基础设施。 TronWeb 是与 TronGrid 或您自己的全节点通信的客户端 SDK。

TronWeb 支持 TypeScript 吗？

使用 @types 社区包或 TronWeb 的捆绑类型（如果可用）。在应用程序代码中使用类型化接口包装合约调用。

我应该使用什么版本？

在主网部署之前，从 npm 固定最新的稳定版本并在 Shasta 上进行测试。