Webpacker依赖排查与更新：解决node-gyp与Python兼容问题

问题背景 #

node-gyp 3.8.0与机器上的Python 3.8.10不兼容，导致应用部署失败，且未修改package.json的情况下突然出现该问题。排查发现由node-sass引发依赖冲突：用户未使用Sass，但*@rails/webpacker 4.3.0*的依赖（node-sass@^4.13.0）自动安装了node-sass 4.14.1，而Webpacker的存在导致node-gyp的多Node.js版本支持特性无法生效。

a) 如何确定哪个依赖触发了node-sass的安装，以判断是否需要更新上游包？ #

• 运行npm ls node-sass（npm环境）或yarn list node-sass（yarn环境）命令，会输出完整依赖树，明确显示node-sass的上游引入源。比如本次场景会看到*@rails/webpacker 4.3.0*是触发源。
• 查看上游包的版本更新记录，确认后续版本是否移除了对旧版node-sass的依赖，或升级到兼容更高Python版本的node-sass分支，以此判断是否需要更新上游包。

b) 在哪里可以找到Python对应版本适配的node-gyp/node-sass版本信息？ #

• node-sass的官方仓库README里有明确的版本兼容表，包含支持的Node.js版本、对应Python版本要求；node-gyp的兼容信息可查看其仓库文档，里面列出了支持的Node.js和Python版本范围。
• 也可直接查看node-sass和node-gyp的npm包页面说明部分，里面标注了详细的版本兼容细节。

c) 应如何修改package.json文件来解决该问题？ #

• 方案一：强制阻止node-sass安装（无需Sass时优先用）：根据包管理器添加对应字段，跳过node-sass的安装：

  // yarn环境使用resolutions
  "resolutions": {
    "node-sass": false
  }
  // npm >=8.0环境使用overrides
  "overrides": {
    "node-sass": false
  }
  

• 方案二：升级上游依赖版本：将*@rails/webpacker*升级到5.x及以上版本，该版本已移除对node-sass的默认依赖，同时同步更新其他相关依赖保证兼容性。
• 方案三：锁定兼容的node-gyp版本：在package.json的devDependencies中手动添加支持Python 3.8的node-gyp版本（如8.x及以上），并通过覆盖字段强制锁定：

  "devDependencies": {
    "node-gyp": "^8.4.1"
  },
  "overrides": {
    "node-gyp": "^8.4.1"
  }
  

d) 若不使用Sass，如何让Webpacker忽略node-sass依赖？ #

• 方法一：依赖覆盖阻止安装：采用上述c方案中的resolutions/overrides字段，直接将node-sass设为false，从根源阻止其被安装。
• 方法二：升级Webpacker版本：将*@rails/webpacker*升级到5.x及以上版本，该版本默认不再捆绑node-sass，且支持完全禁用Sass相关配置。
• 方法三：修改Webpacker配置：在config/webpack/environment.js等配置文件中，移除所有Sass相关加载器配置，同时确保项目中无Sass文件引入。但此方法仅规避调用，不如依赖覆盖彻底。

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