Thirdweb是一个面向Web3应用的全栈开发平台，它把钱包连接、合约部署、链上数据交互这些原本琐碎的能力封装成了统一的SDK和Dashboard。如果你的团队已经有一个基于React的应用，想让它具备连接钱包、铸造NFT、读取链上数据等能力，把项目迁移到Thirdweb体系里通常是性价比最高的路线——你不需要自己维护一套ethers.js的封装，也不需要为钱包弹窗、网络切换这些边界情况写大量兼容代码。这篇文章会完整拆解迁移的每一步，包括依赖安装、代码改造、合约部署与联调。
迁移前的准备：梳理现有项目的Web3依赖
动手改代码之前，先把项目里所有和链上交互相关的依赖列出来。常见的有ethers.js、web3.js、@walletconnect相关包，以及各种自己封装的connect、sign工具函数。这些内容在迁移后大部分会被Thirdweb SDK替代，如果不提前梳理清楚，很容易出现两套钱包状态管理互相打架的情况。
建议先在项目根目录执行依赖检查，确认当前使用的版本和引用位置：
npm ls ethers web3 @walletconnect # 或者使用 yarn yarn why ethers
梳理完之后，把所有直接调用window.ethereum的地方标记出来，这些是迁移的重点。Thirdweb的useConnect、useAddress等Hook会统一接管这部分逻辑，原生provider的裸调用应该逐步替换掉。另外，如果项目里已经有部署好的合约地址和ABI文件，把它们整理到一个单独的目录（比如src/contracts），后面接入Thirdweb SDK时会直接复用，不需要重新部署。
安装Thirdweb SDK并替换钱包连接层
Thirdweb官方对React的支持非常完整，核心包是@thirdweb-dev/react和@thirdweb-dev/sdk。前者提供组件和Hook，后者提供底层的合约交互能力。安装命令如下：
npm install @thirdweb-dev/react @thirdweb-dev/sdk ethers
装好之后，第一步是在应用入口用ThirdwebProvider包裹根组件。这个Provider负责管理钱包连接状态、当前链以及内置的合约实例缓存。最关键的是activeChain和supportedChains两个配置，前者决定默认连接的链，后者列出应用支持的所有链，用户切到不支持的链时会自动提示切换。
import { ThirdwebProvider, metamaskWallet, coinbaseWallet } from "@thirdweb-dev/react";
import { Ethereum, Polygon, Mumbai } from "@thirdweb-dev/chains";
function App({ children }) {
return (
<ThirdwebProvider
activeChain={Polygon}
supportedChains={[Ethereum, Polygon, Mumbai]}
walletConfig={[metamaskWallet(), coinbaseWallet()]}
clientId="你的客户端ID"
>
{children}
</ThirdwebProvider>
);
}
export default App;接下来把原来的连接按钮替换掉。传统写法里，连接MetaMask需要自己监听accountsChanged事件、处理用户拒绝授权的异常、维护连接状态。迁移到Thirdweb后，这些全部由useConnect和useConnectionStatus两个Hook承担：
import { useConnect, useAddress, useDisconnect, useConnectionStatus } from "@thirdweb-dev/react";
function ConnectButton() {
const connect = useConnect();
const address = useAddress();
const disconnect = useDisconnect();
const status = useConnectionStatus();
if (status === "connected") {
return (
<div>
<p>已连接: {address}</p>
<button onClick={disconnect}>断开连接</button>
</div>
);
}
return (
<button
onClick={async () => {
await connect.metamask();
}}
>
连接钱包
</button>
);
}对比直接使用ethers.js的写法，代码量大约能减少一半以上，而且钱包适配由SDK统一处理。原先针对不同钱包写的兼容分支（比如WalletConnect的移动端跳转逻辑）都可以删掉，这会显著降低后期维护成本。
接入智能合约：从部署到调用
Thirdweb提供了两种使用合约的方式。第一种是直接在Thirdweb的Dashboard网页上部署预置合约，比如ERC-721、ERC-1155、代币合约等，部署完成后拿到合约地址，前端直接引用。第二种是使用Thirdweb CLI部署自己编写的Solidity合约，适合有定制需求的团队。
如果选择CLI方式，在终端执行初始化命令即可创建合约工程：
npx thirdweb create contract # 按提示选择Solidity或Hardhat模板，然后编写合约逻辑 # 部署时执行 npx thirdweb deploy
部署完成后，回到React端用useContractHook获取合约实例，再用useContractRead和useContractWrite读写链上数据。假设你部署了一个NFT合约，读取总供应量和执行铸造的代码如下：
import { useContract, useContractRead, useContractWrite } from "@thirdweb-dev/react";
function MintSection() {
const { contract } = useContract("你的合约地址");
const { data: totalSupply } = useContractRead(contract, "totalSupply");
const { mutateAsync: mint } = useContractWrite(contract, "mint");
const handleMint = async () => {
try {
const tx = await mint({ to: "接收地址", tokenId: 1, quantity: 1 });
console.log("交易哈希:", tx.receipt.transactionHash);
} catch (e) {
console.error("铸造失败:", e);
}
};
return (
<div>
<p>当前已铸造: {totalSupply?.toNumber() ?? 0}</p>
<button onClick={handleMint}>铸造NFT</button>
</div>
);
}useContractRead自带缓存和自动刷新，链上状态变化时组件会自动更新，这一点比自己用ethers.js监听事件再手动setState要省心得多。对于需要实时监听事件的场景，比如铸造完成后的通知，可以配合useContractEvents使用，它内部封装了事件的订阅与清理逻辑，组件卸载时会自动取消订阅，避免内存泄漏。
迁移常见坑点与排查思路
第一个高频问题是网络切换不生效。原因是ThirdwebProvider的activeChain只在初始化时生效，动态切换链时需要通过desiredChainId参数或者直接修改Provider配置来驱动，而不是只在前端改一个本地状态。排查时可以先打印useNetwork返回的当前链，确认是SDK状态没变还是钱包侧没切换。
第二个问题是签名窗口重复弹出。这通常发生在短时间内多次触发useContractWrite的场景，比如用户快速点击按钮。解决方式是在触发函数里加防抖或者用isLoading状态禁用按钮，Thirdweb的Hook在交易进行中会返回loading状态，直接用它控制按钮的可用性即可：
const { mutateAsync: mint, isLoading } = useContractWrite(contract, "mint");
<button disabled={isLoading} onClick={handleMint}>
{isLoading ? "交易进行中..." : "铸造NFT"}
</button>第三个需要注意的点是环境变量里的密钥管理。Thirdweb的clientId或者secretKey建议放在.env文件中，并且把.env加入版本控制忽略列表。客户端侧只使用clientId，涉及需要私钥权限的服务端操作（比如批量空投）才使用secretKey，并且只在Node.js环境运行，绝不能打进前端产物。
最后，迁移完成后建议做一轮完整的回归测试，重点覆盖钱包断开重连、链切换、交易失败重试这几个路径。可以在测试环境把RPC故意断开，验证应用的错误提示是否友好。整体迁移工作量对于中等规模的React项目来说通常在两到三天内可以完成，换来的是钱包兼容性、合约交互稳定性上的大幅提升，长期看是非常划算的一次重构。