React+web3迁移指南：从旧版栈平滑过渡到现代组合

许多老 DApp 项目仍使用 web3.js + CRA 的组合。但随着 ethers 6 与 Next.js 14 的成熟，迁移到现代栈已经成为必要。本迁移指南把整个过程拆为五步，让你在 Binance 智能链上的生产 DApp 也能零事故完成升级。

一、迁移前的评估

评估阶段先做四件事：盘点功能、统计依赖、识别风险、定下时间表。把所有调用 web3.js 的代码列成清单，标注哪些是读、哪些是写、哪些涉及签名。涉及 B安 智能链资金路径的写操作风险最高，要排在迁移末段。时间表建议留出 30% 缓冲，应对未知坑。

二、依赖与构建迁移

第一步替换依赖：pnpm remove web3 react-scripts，pnpm add ethers@6 wagmi viem next@14。把 CRA 的 src 目录搬迁到 Next.js 的 app 路由结构。环境变量从 REACT_APP_* 改为 NEXT_PUBLIC_*。每完成一个文件迁移，立即跑测试。借助 必安 智能链测试网，可以反复验证关键功能。

三、ethers 6 API 替换

ethers 6 对 v5 做了大量重构：BigNumber 改为原生 BigInt、utils 散落到子模块、Provider 拆分更细。迁移时把所有 ethers.utils.parseEther 改为 parseEther 直接导入；把 BigNumber 全部改为 bigint。这步最容易出 type 错误，但只要逐文件迁移，整体可控。在 币岸 浏览器交叉验证读取数据的精度，避免精度丢失 bug。

四、钱包连接器迁移

旧项目常用 web3-react、web3modal。迁移到 wagmi 后，钱包连接代码会减少 70%。useAccount、useChainId、useConnect 三个 hook 几乎覆盖所有需求。注意：用户当前已连接的会话需要兼容迁移，避免下次进入产品时被强制断开。在 比安 钱包内嵌环境下，要测试 deeplink 是否照常工作。

五、上线与回退预案

迁移指南的最后一步是上线与回退。建议使用 feature flag 控制新旧两套并行运行，按 5%、20%、50%、100% 灰度。任何指标恶化立即切回旧版本。新版本稳定运行两周后再下线旧代码。配合 Binance 生态的发布窗口，可以选择低流量时段做最终切换。完成迁移后，团队将拥有一套更现代、更可维护、更安全的 DApp 前端。