本地运行Ruby项目用yarn install安装node-sass依赖时失败报错

核心诱因 #

三个问题是叠加触发的，单独解决某一项都没法顺利完成安装：

• 版本不兼容：项目依赖的node-sass@^4.14.1官方最高仅支持Node 14.x系列，你本地使用的Node 15.14.0已经超出兼容范围。同时node-sass 4.x自带老旧的node-gyp@3.8.0编译工具，这个版本的工具根本无法适配Node 15的内部接口。
• Python解释器版本不匹配：报错日志里的语法错误，本质是node-gyp 3.8.0默认查找Python2解释器，但系统里默认的/usr/bin/python指向Python 3。日志里执行的print "%s.%s.%s" % sys.version_info[:3]是Python 2专属语法，在Python 3环境下必然触发SyntaxError，直接中断配置流程。
• 全局依赖无法覆盖项目依赖：你之前单独全局安装的node-sass@5.0.0和项目要求的4.14.1版本不一致，全局安装的包完全不会影响项目node_modules目录下的实际安装版本，所以重装后报错完全没有变化。

补充说明：node-sass 4.14.1 确实是@rails/webpacker@5.2.1的内置配套依赖，并不是你安装流程出错引入的问题。

解决方案（按推荐优先级排序） #

方案1：切到匹配的Node版本（无侵入，不改动项目文件） #

这是对第一次贡献代码最友好的方案，完全不会改动项目原有配置，也不会和上游仓库的依赖要求冲突：

• 用nvm安装并切换到Node 14.x长期支持版，这是node-sass 4.14.1官方完整兼容的环境：
  • 执行nvm install 14
  • 执行nvm use 14
• 清理旧的编译残留：删除项目下的node_modules目录，清空yarn的本地缓存残留
• 重新执行yarn install

这个环境下node-sass会直接下载对应平台的预编译二进制文件，根本不会触发本地node-gyp的编译流程，也就不会碰到Python版本不匹配的问题。如果切换后仍有Python相关报错，只需要执行yarn config set python /usr/bin/python3指定解释器路径即可，不需要额外安装Python 2。

方案2：保留当前Node版本的临时修复 #

如果必须使用Node 15环境，可以通过强制兼容参数绕过校验，但可能会在后续编译阶段碰到其他语法不兼容问题，不推荐长期使用：

• 指定node-gyp使用系统Python3解释器：执行export PYTHON=/usr/bin/python3
• 替换node-sass内置的老旧node-gyp版本：执行yarn add node-gyp@8.0.0 --ignore-scripts，让编译流程适配新Node的接口
• 重新执行yarn install

注意事项 #

• 不要强行把项目里的node-sass升级到适配Node 15的新版本：会直接和@rails/webpacker@5.2.1的配置产生兼容冲突，后续提交PR时也会和上游的依赖配置冲突
• 不要尝试通过全局安装新版本node-sass解决问题：全局依赖永远无法覆盖项目本地指定的依赖版本，完全起不到修复作用

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