Angular项目npm install遇node-gyp报错：缺失Python/VS环境如何解决？

我用VSCode开发，环境是node v16.13.2、npm 8.15.0。创建Angular项目后逐个安装依赖一切正常，但删除node_modules再执行npm install时，触发node-gyp报错：先是提示找不到Python，装完Python又要求安装带「Desktop development with C++」 workload的Visual Studio。我用npm install --ignore-scripts临时解决了，但疑惑是不是所有常规项目都得这么做，还是必须安装Python、C++及VS环境？求正常执行npm install的标准方案。

复现步骤 #

ng new demo-app 
# 启用路由与scss
cd demo-app
npm install primeng --save
npm install primeicons --save
npm install bootstrap --save
npm install @angular/material --save
npm install @angular/cdk --save
# 此时npm start可正常运行
del /f/s/q node_modules & rmdir node_modules
npm install
# 报错出现

项目package.json配置 #

{
  "name": "angular-demo",
  "version": "0.0.0",
  "scripts": {
    "ng": "ng",
    "start": "ng serve --port=4202 --open",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test": "ng test"
  },
  "private": true,
  "dependencies": {
    "@angular/animations": "^14.2.0",
    "@angular/cdk": "^14.2.6",
    "@angular/common": "^14.2.0",
    "@angular/compiler": "^14.2.0",
    "@angular/core": "^14.2.0",
    "@angular/forms": "^14.2.0",
    "@angular/material": "^14.2.6",
    "@angular/platform-browser": "^14.2.0",
    "@angular/platform-browser-dynamic": "^14.2.0",
    "@angular/router": "^14.2.0",
    "bootstrap": "^5.2.2",
    "primeicons": "^6.0.1",
    "primeng": "^14.1.2",
    "rxjs": "~7.5.0",
    "tslib": "^2.3.0",
    "zone.js": "~0.11.4"
  },
  "devDependencies": {
    "@angular-devkit/build-angular": "^14.2.2",
    "@angular/cli": "~14.2.2",
    "@angular/compiler-cli": "^14.2.0",
    "@types/jasmine": "~4.0.0",
    "jasmine-core": "~4.3.0",
    "karma": "~6.4.0",
    "karma-chrome-launcher": "~3.1.0",
    "karma-coverage": "~2.2.0",
    "karma-jasmine": "~5.1.0",
    "karma-jasmine-html-reporter": "~2.0.0",
    "typescript": "~4.7.2"
  }
}

问题原因 #

node-gyp是Node.js的原生模块编译工具，你的项目中@angular/cdk等依赖包含需要编译的原生代码。第一次逐个安装时，npm可能利用了预编译二进制缓存，删除node_modules后缓存失效，重新安装需要触发编译流程，因此触发node-gyp的环境检查。

标准解决方案 #

方案1：安装node-gyp完整依赖环境（推荐） #

这是长期解决所有同类问题的根本方法，步骤如下：

• 安装Python 3.7-3.10版本（node-gyp对Python版本有严格要求，过高/过低版本可能不兼容），安装时务必勾选「Add Python to PATH」
• 安装Visual Studio 2019或更高版本，安装时必须勾选「Desktop development with C++」工作负载，该负载包含MSVC编译器、Windows SDK等编译必需组件
• 配置npm关联已安装的Python和Visual Studio版本：

  npm config set python python3.9  # 替换为你实际安装的Python版本号
  npm config set msvs_version 2019  # 替换为你实际安装的Visual Studio版本号
  

• 配置完成后执行npm install即可正常完成原生模块编译

方案2：用--ignore-scripts临时规避（不推荐长期使用） #

npm install --ignore-scripts会跳过所有依赖的预安装/编译脚本，虽然能快速完成安装，但存在明显风险：

• 未编译的原生模块可能在项目运行时出现功能异常、崩溃等问题
• 后续更新依赖或新增带原生代码的依赖时，仍会触发相同报错

为什么第一次逐个安装无报错？ #

第一次逐个安装依赖时，npm可能自动复用了Angular CLI或依赖包提供的预编译二进制缓存包（部分依赖会针对常见Node版本和系统提前编译好二进制文件），无需本地编译。删除node_modules后缓存被清除，重新安装时必须本地编译原生模块，因此触发了node-gyp的环境检查。

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