Gatsby生产构建引入websocket-node出现Webpack内置调用警告如何解决

问题根因 #

该警告是Gatsby静态构建（SSG）阶段的特性导致的：构建时会在Node.js环境加载所有站点代码，而websocket-node同时包含服务端+客户端实现，依赖fs、http这类仅Node环境可用的内置模块，静态构建阶段识别到浏览器侧代码引入了Node原生模块就会抛出警告。之前的loadable、虚拟组件配置没生效，是因为不仅组件层引入了websocket，工具层src/utils/hub.js的顶层导入逻辑在静态构建阶段就触发了包加载。

解决方案 #

第一步：修改websocket工具文件，做环境判断兜底

在你引入websocket的src/utils/hub.js里，仅浏览器环境才加载websocket相关代码，Node静态构建阶段直接跳过：

// src/utils/hub.js
let W3CWebSocket = null
let wsInstance = null

// 只有浏览器环境才导入websocket包
if (typeof window !== 'undefined') {
  W3CWebSocket = require('websocket').w3cwebsocket
}

export const initWebSocket = () => {
  // 非浏览器环境直接返回，不执行逻辑
  if (!W3CWebSocket) return
  wsInstance = new W3CWebSocket('ws://你的websocket服务地址')
  // 所有websocket监听、消息处理逻辑都写在这里
  wsInstance.onmessage = (msg) => {
    // 处理消息逻辑
  }
}

第二步：配置gatsby-node.js，屏蔽Node原生模块解析

如果第一步做完仍有警告，修改项目根目录的gatsby-node.js，添加webpack配置，客户端构建阶段跳过Node原生模块的解析：

// gatsby-node.js
exports.onCreateWebpackConfig = ({ stage, actions }) => {
  // 仅处理客户端构建阶段
  if (stage === 'build-javascript' || stage === 'develop') {
    actions.setWebpackConfig({
      externals: {
        'websocket': 'commonjs websocket',
        'bufferutil': 'commonjs bufferutil',
        'utf-8-validate': 'commonjs utf-8-validate',
      },
      node: {
        fs: 'empty',
        http: 'empty',
        net: 'empty',
        tls: 'empty',
      }
    })
  }
}

第三步：可选，移除无用的可选依赖

websocket依赖的bufferutil、utf-8-validate是服务端用的C++扩展优化包，浏览器端完全不需要，你可以在package.json中添加配置，安装依赖时自动跳过这两个包：

{
  "optionalDependencies": {
    "bufferutil": false,
    "utf-8-validate": false
  }
}

配置完成后删除node_modules和锁文件，重新安装依赖即可。

额外注意 #

所有调用websocket初始化方法的逻辑，都要放在客户端专属的生命周期里执行，比如React组件的useEffect钩子：

import { initWebSocket } from '../utils/hub'

function YourPage() {
  // 组件挂载后再初始化websocket
  useEffect(() => {
    initWebSocket()
  }, [])

  return <div>页面内容</div>
}

以上步骤全部执行完成后，重新运行gatsby build就不会再出现对应的警告，且浏览器端websocket功能不受任何影响。

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