macOS下yarn/npm install因CPP错误致make失败求助

在macOS设备上通过package.json安装项目依赖时，使用yarn install和npm install均因CPP错误导致安装失败，报错显示make执行失败、node-gyp构建出错，核心涉及node-sass依赖。尝试更换多个Node.js版本未解决，但Windows WSL环境下无此问题。

具体报错信息 #

1 error generated.
make: *** [Release/obj.target/binding/src/binding.o] Error 1
gyp ERR! build error 
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack     at ChildProcess.onExit (/Users/florian/code/project/inscriptions-v2/node_modules/node-gyp/lib/build.js:262:23)
gyp ERR! stack     at ChildProcess.emit (node:events:527:28)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (node:internal/child_process:291:12)
gyp ERR! System Darwin 21.5.0
gyp ERR! command "/usr/local/bin/node" "/Users/florian/code/project/inscriptions-v2/node_modules/node-gyp/bin/node-gyp.js" "rebuild" "--verbose" "--libsass_ext=" "--libsass_cflags=" "--libsass_ldflags=" "--libsass_library="
gyp ERR! cwd /Users/florian/code/project/inscriptions-v2/node_modules/vue-loading-spinner/node_modules/node-sass
gyp ERR! node -v v16.16.0

项目package.json依赖配置 #

"dependencies": {
    "@fortawesome/fontawesome-svg-core": "^1.3.0",
    "@fortawesome/free-solid-svg-icons": "^6.1.1",
    "@fortawesome/vue-fontawesome": "^2.0.6",
    "@lyracom/embedded-form-glue": "^1.0.0",
    "@popperjs/core": "^2.11.5",
    "axios": "^0.21.1",
    "bootstrap": "^5.1.3",
    "core-js": "^3.6.5",
    "css-loader": "^6.7.1",
    "jquery": "^3.6.0",
    "lodash": "^4.17.21",
    "moment": "^2.29.2",
    "popper.js": "^1.16.1",
    "postcss-loader": "^6.2.1",
    "qs": "^6.10.3",
    "register-service-worker": "^1.7.1",
    "sass": "^1.49.11",
    "vue": "^2.6.11",
    "vue-form-wizard": "^0.8.4",
    "vue-head": "^2.2.0",
    "vue-loading-spinner": "^1.0.11",
    "vue-moment": "^4.1.0",
    "vue-progressbar": "^0.7.5",
    "vue-router": "^3.5.3",
    "vue-simple-spinner": "^1.2.10",
    "vue-stepper": "^1.4.2",
    "vue-toastr": "^2.1.2"
  },
  "devDependencies": {
    "@vue/cli-plugin-babel": "~4.5.15",
    "@vue/cli-plugin-eslint": "~4.5.15",
    "@vue/cli-plugin-pwa": "~4.5.19",
    "@vue/cli-service": "~4.5.15",
    "babel-eslint": "^10.1.0",
    "eslint": "^6.7.2",
    "eslint-plugin-vue": "^6.2.2",
    "node-sass": "^7.0.1",
    "sass-loader": "^10",
    "vue-template-compiler": "^2.6.11"
  }

解决方案 #

• 安装Xcode命令行工具并接受协议
  执行以下命令安装编译所需的基础环境：

  xcode-select --install
  sudo xcodebuild -license accept
  

• 配置node-gyp的Python环境
  指定node-gyp使用Python3（macOS默认已预装）：

  npm config set python python3
  

• 替换node-sass为dart-sass（推荐）
  node-sass已停止维护，与新版本Node兼容性差。修改package.json：
  1. 删除devDependencies中的node-sass依赖
  2. 确保已保留sass依赖（项目中已存在"sass": "^1.49.11"）
  3. 删除node_modules、package-lock.json/yarn.lock文件
  4. 重新执行npm install或yarn install
• 强制替换嵌套依赖中的node-sass
  部分第三方包（如vue-loading-spinner）内部依赖旧版node-sass，可通过包管理器的覆盖功能强制替换：
  • 若使用yarn，在package.json中添加：

    "resolutions": {
      "node-sass": "^7.0.1"
    }
    

  • 若使用npm（版本8+），在package.json中添加：

    "overrides": {
      "node-sass": "$sass"
    }
    

  之后重新执行安装命令
• 清理缓存后重装
  清理npm/yarn缓存，避免缓存文件导致的问题：

  # npm
  npm cache clean --force
  rm -rf node_modules package-lock.json
  npm install
  
  # yarn
  yarn cache clean
  rm -rf node_modules yarn.lock
  yarn install
  

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