Gatsby生产构建失败提示node:crypto未被插件处理，开发构建正常

问题背景 #

使用TypeScript开发Gatsby 5.11.0项目，执行yarn build时出现以下SSR报错：

Reading from "node:crypto" is not handled by plugins (Unhandled scheme).
Webpack supports "data:" and "file:" URIs by default.
You may need an additional plugin to handle "node:" URIs.
not finished Building HTML renderer - 8.371s
error Command failed with exit code 1.

yarn start开发服务运行正常，问题自wagmi更新至1.3.10后出现，已尝试替换crypto-browserify、检查Node专属模块、清理缓存、更新依赖、排查冲突等方案。

针对性解决方案 #

1. 配置Webpack处理node:协议 #

在项目根目录的gatsby-node.js中添加自定义Webpack配置，让Webpack识别node:前缀的模块并提供polyfill：

exports.onCreateWebpackConfig = ({ actions, getConfig }) => {
  const config = getConfig();

  // 解析node:前缀的模块，移除前缀转为普通模块请求
  config.resolve.plugins = config.resolve.plugins || [];
  config.resolve.plugins.push({
    apply(resolver) {
      resolver.hooks.resolve.tap('NodeSchemeResolver', (request) => {
        if (request.request?.startsWith('node:')) {
          request.request = request.request.slice(5);
        }
      });
    },
  });

  // 为crypto模块添加浏览器兼容的polyfill
  config.resolve.fallback = {
    ...config.resolve.fallback,
    crypto: require.resolve('crypto-browserify'),
  };

  // 修复ES模块导入的完全指定路径问题
  config.module.rules.push({
    test: /\.m?js$/,
    resolve: {
      fullySpecified: false,
    },
  });

  actions.replaceWebpackConfig(config);
};

添加后记得安装依赖：

yarn add crypto-browserify stream-browserify buffer -D

2. 避免SSR阶段加载依赖Node模块的wagmi代码 #

通过动态导入或客户端环境判断，让wagmi相关代码仅在浏览器环境执行：

import { useEffect, useState } from 'react';
import type { Client } from 'wagmi';

const WagmiDappComponent = () => {
  const [client, setClient] = useState<Client | null>(null);

  useEffect(() => {
    // 仅在客户端初始化wagmi
    const initWagmiClient = async () => {
      const { createClient, configureChains, mainnet } = await import('wagmi');
      const { publicProvider } = await import('wagmi/providers/public');

      const { chains, provider, webSocketProvider } = configureChains(
        [mainnet],
        [publicProvider()]
      );

      const wagmiClient = createClient({
        autoConnect: true,
        provider,
        webSocketProvider,
      });

      setClient(wagmiClient);
    };

    initWagmiClient();
  }, []);

  if (!client) return <div>Loading...</div>;

  return (
    // 渲染你的Dapp组件
  );
};

export default WagmiDappComponent;

3. 临时降级wagmi版本 #

若上述方案无效，可先降级至之前兼容的版本（如1.3.9），等待wagmi官方修复SSR兼容性问题：

yarn add wagmi@1.3.9

4. 配置Webpack externals排除SSR模块 #

在gatsby-node.js中添加externals配置，让Webpack在SSR阶段跳过处理node:crypto相关模块：

exports.onCreateWebpackConfig = ({ actions }) => {
  actions.setWebpackConfig({
    externals: {
      'node:crypto': 'crypto',
      crypto: 'crypto',
    },
  });
};

内容的提问来源于stack exchange，提问作者Ishaan Patel