部署web3应用到Heroku时出现node-gyp-build not found错误如何解决

问题根本原因 #

该报错的核心原因是web3@1.3.6依赖的可选原生模块bufferutil在安装时需要执行node-gyp-build命令，而Heroku自动构建阶段的环境中，该命令还未被加载完成，导致执行失败。你SSH登录后全局安装成功是因为SSH环境和Heroku自动构建的环境相互隔离，全局安装的包不会作用于自动构建流程。

可执行解决方案 #

• 方案一：忽略可选原生依赖（最简便，不影响web3正常功能）
  在项目根目录新增.npmrc文件，添加如下配置：

  optional = false
  

  该配置会让npm跳过所有可选依赖的安装，bufferutil和同类型的utf-8-validate都是ws库的可选优化依赖，纯JS运行环境下web3完全可以正常运行，不需要这两个原生模块。

• 方案二：预安装构建依赖
  如果必须保留原生模块的安装，在package.json的scripts字段中新增preinstall钩子，让构建流程在安装所有依赖前先全局安装需要的构建工具：

  "scripts": {
    "preinstall": "npm install -g node-gyp node-gyp-build",
    "deploy": "webpack --mode production",
    "watch": "webpack --mode development --watch"
  },
  

  该钩子会在npm执行install命令前自动运行，提前把构建需要的命令装到全局环境中，避免后续执行bufferutil安装脚本时找不到命令。

• 方案三：调整安装顺序
  如果不想全局安装构建工具，可以把node-gyp-build添加到package.json的bundledDependencies字段中，保证它会优先于其他依赖被安装：

  "dependencies": {
    "node-gyp-build": "^4.2.0",
    // 其余原有依赖保持不变
  },
  "bundledDependencies": ["node-gyp-build"]
  

注意事项 #

修改配置后部署时，建议先清空Heroku的构建缓存避免旧缓存影响效果，执行命令：heroku builds:cache:purge -a 你的Heroku应用名称，之后重新推送代码部署即可。

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