安装MetaMask后React Web3应用DOM无法正常渲染问题排查

该问题属于依赖兼容+构建配置问题，仅在安装MetaMask时触发的原因是：

• 你在Main.jsx中导入了web3@1.7.4但未实际调用，该版本web3的入口脚本在浏览器环境运行时，会自动检测全局的window.ethereum对象：未安装MetaMask时该对象不存在，web3不会触发后续旧版Dapp兼容逻辑，代码无报错；安装MetaMask后window.ethereum被插件注入，web3自动执行的兼容逻辑会调用Buffer、process等Node.js专属全局对象。而你使用的react-scripts 5基于webpack 5构建，默认不再自动注入Node核心模块的polyfill，如果之前的polyfill配置存在遗漏，就会直接抛出引用错误，导致整个React应用渲染树崩溃，最终页面只剩空的root节点。
• React 18默认开启的严格模式会放大兼容问题：严格模式下组件首次挂载时useEffect会执行「挂载-卸载-重挂载」的双调用，@metamask/onboarding@1.0.1版本没有做实例防重处理，重复初始化、重复绑定事件时会触发内部DOM操作冲突，也会导致白屏。

按优先级从高到低操作即可快速定位：

• 打开浏览器开发者工具Console面板，直接查看抛出的错误信息，90%以上的场景会直接提示Buffer is not defined、process is not defined或事件绑定相关类型错误，直接锁定问题点。
• 临时注释Main.jsx中的import Web3 from 'web3'行，刷新页面如果恢复渲染，即可确定是web3导入触发的polyfill缺失问题。
• 临时注释src/index.js中包裹App组件的<React.StrictMode>标签，刷新页面如果恢复渲染，即可确定是React 18严格模式与MetaMask onboarding库的兼容问题。
• 逐段注释OnboardingButton组件中的useEffect逻辑，定位具体触发报错的代码段。

1. 清理无效导入：如果Main.jsx中暂时不需要使用Web3实例，直接删除import Web3 from 'web3'行，避免无意义的入口脚本执行。
2. 补全polyfill配置：如果需要使用web3，先安装缺失的polyfill依赖，执行npm install buffer process crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url path-browserify，通过react-app-rewired或者直接修改webpack配置，在resolve.fallback中补充对应Node核心模块的浏览器端polyfill映射，同时在webpack插件中添加new webpack.ProvidePlugin({ Buffer: ['buffer', 'Buffer'], process: 'process/browser' })，注入缺失的全局对象。
3. 修复onboarding实例重复初始化问题：给实例增加兜底判断，同时在useEffect清理函数中终止引导流程，避免严格模式下重复创建实例：

   useEffect(() => {
       if (!onboarding.current) {
           onboarding.current = new MetaMaskOnboarding();
       }
       return () => {
           onboarding.current?.stopOnboarding();
       }
   }, []);
   

4. 给钱包相关方法加安全兜底：访问window.ethereum的方法时增加可选链判断，避免特殊场景下对象存在但方法缺失触发报错，事件绑定和连接逻辑修改为：

   // 账号变更事件绑定
   useEffect(() => {
       function handleNewAccounts(newAccounts) {
           setAccounts(newAccounts);
       }
       if (MetaMaskOnboarding.isMetaMaskInstalled() && window.ethereum?.on && window.ethereum?.off) {
           window.ethereum.on('accountsChanged', handleNewAccounts);
           return () => {
               window.ethereum.off('accountsChanged', handleNewAccounts);
           };
       }
   }, []);
   
   // 按钮点击逻辑
   const onClick = () => {
       if (MetaMaskOnboarding.isMetaMaskInstalled() && window.ethereum?.request) {
           window.ethereum
               .request({ method: 'eth_requestAccounts' })
               .then((newAccounts) => setAccounts(newAccounts))
               .catch(err => console.error('钱包连接失败', err));
       } else {
           onboarding.current?.startOnboarding();
       }
   };
   

内容的提问来源于stack exchange，提问作者n Z