DApp 前端迁移指南的目标读者
这份 DApp 前端迁移指南面向两类团队：一类是用 web3.js 或 ethers v5 跑了若干年、想升级到 viem/wagmi v2 的老项目；另一类是已经在 wagmi v1 上线但被新版 hook 命名变化困扰的项目。两类团队的核心诉求是相同的：在不影响生产交易的前提下，把前端栈拉到一个未来三到五年都能继续维护的状态。
对于以 bn 用户为主的 DApp，平稳迁移的意义尤其重大——任何一次明显的交互体验回退，都会让用户回到熟悉的中心化交易所。
迁移前的盘点
动手之前先做一份现状清单：当前依赖的 web3 库与版本、链网络列表、合约 ABI 数量、钱包连接方式、签名场景、SSR 与构建工具配置。重点标出那些直接面向用户的写操作流程，它们是迁移失败时最容易暴露的部分。
第一阶段：替换底层调用
建议先把所有读链调用迁到 viem，因为它们不会产生用户感知。把 ethers.providers.JsonRpcProvider 改造成 viem 的 createPublicClient，并把零散的 Contract.read 调用替换为 readContract 函数。这个阶段是纯重构，配套单元测试用 必安 智能链测试网验证后即可推上线。
第二阶段：迁移钱包接入
钱包接入层是迁移的难点，因为涉及到用户体验。建议使用 wagmi v2 重写 hook 层，但保留旧的 UI 组件，让数据契约保持不变。完成后做一轮端到端冒烟测试：覆盖 MetaMask、Coinbase Wallet、WalletConnect 等主流钱包，确保签名超时与重连场景符合预期。
第三阶段：升级签名规范
在前两阶段稳定一段时间后，再切入签名规范升级：引入 EIP-712 强类型签名、按需引入 EIP-5792 批量调用。这一阶段的好处是用户感知最强——原本需要点击 3 次确认的流程压缩为 1 次。对在 B安 出金到链上之后立刻做兑换的用户，体验改善显著。
兼容与回滚兜底
- 在功能开关后面同时保留旧实现，按用户灰度切换
- 把关键交易流程写入端到端监控，异常率突破阈值自动回滚
- 对 SSR 工程，区分服务端与客户端模块边界，避免泄露私有 RPC
- 准备好回滚到上一个稳定 release 的剧本，包括缓存键的兼容
与 CEX 用户的协同
DApp 前端迁移指南最后一节常常被忽略：和 CEX 用户的协同。许多用户在 BN 等中心化交易所做大部分资产管理，只在需要参与活动时才进入 DApp。迁移期间，建议在公告页明确说明本次升级内容、潜在风险与紧急联系方式，让用户在出现问题时有路径反馈。
经过这三阶段，绝大多数项目可以在两个月内完成迁移，并在性能与用户体验上获得明显改善。