升级Node.js至20.9.0时node-gyp相关报错求助

我正在将服务从Node.js 14升级至20.9.0，已完成Docker文件、.nvmrc文件等的更新，但使用Node.js 20.9.0执行npm install时遇到以下node-gyp报错，无法找到解决方法，恳请提供思路：

npm ERR! path /Users/faljawhary/Desktop/forks/pkg-transformations/node_modules/node-expat
npm ERR! command failed
npm ERR! command sh -c node-gyp rebuild
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using node-gyp@9.4.0
npm ERR! gyp info using node@20.9.0 | darwin | arm64
npm ERR! gyp info find Python using Python version 3.9.6 found at "/Library/Developer/CommandLineTools/usr/bin/python3"
npm ERR! gyp http GET https://nodejs.org/download/release/v20.9.0/node-v20.9.0-headers.tar.gz
npm ERR! (node:22309) Warning: Setting the NODE_TLS_REJECT_UNAUTHORIZED environment variable to '0' makes TLS connections and HTTPS requests insecure by disabling certificate verification.
npm ERR! (Use `node --trace-warnings ...` to show where the warning was created)
npm ERR! gyp WARN install got an error, rolling back install
npm ERR! gyp ERR! configure error 
npm ERR! gyp ERR! stack FetchError: request to https://nodejs.org/download/release/v20.9.0/node-v20.9.0-headers.tar.gz failed, reason: 
npm ERR! gyp ERR! stack     at ClientRequest.<anonymous> (/Users/faljawhary/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/minipass-fetch/lib/index.js:130:14)
npm ERR! gyp ERR! stack     at ClientRequest.emit (node:events:514:28)
npm ERR! gyp ERR! stack     at TLSSocket.socketErrorListener (node:_http_client:495:9)
npm ERR! gyp ERR! stack     at TLSSocket.emit (node:events:526:35)
npm ERR! gyp ERR! stack     at emitErrorNT (node:internal/streams/destroy:151:8)
npm ERR! gyp ERR! stack     at emitErrorCloseNT (node:internal/streams/destroy:116:3)
npm ERR! gyp ERR! stack     at process.processTicksAndRejections (node:internal/process/task_queues:82:21)
npm ERR! gyp ERR! System Darwin 23.2.0
npm ERR! gyp ERR! command "/Users/faljawhary/.nvm/versions/node/v20.9.0/bin/node" "/Users/faljawhary/.nvm/versions/node/v20.9.0/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
npm ERR! gyp ERR! cwd /Users/faljawhary/Desktop/forks/pkg-transformations/node_modules/node-expat
npm ERR! gyp ERR! node -v v20.9.0
npm ERR! gyp ERR! node-gyp -v v9.4.0
npm ERR! gyp ERR! not ok

npm ERR! A complete log of this run can be found in: /Users/faljawhary/.npm/_logs/2023-12-26T17_28_54_829Z-debug-0.log

我已在Mac上尝试安装Python并执行以下命令：

pyenv install 2.7.18
pyenv global 2.7.18
export PATH="${HOME}/.pyenv/shims:${PATH}"
echo $PATH
npm config set python $(which python)
npm config list 

错误已从“Python not found”变为上述新报错。

可能的解决方向 #

• 排查网络与TLS证书问题
  报错核心是无法下载Node.js headers包，先确认网络连通性：

  • 直接在浏览器访问https://nodejs.org/download/release/v20.9.0/node-v20.9.0-headers.tar.gz，验证能否正常下载
  • 若处于代理环境，配置npm代理：

    npm config set proxy http://your-proxy-address:port
    npm config set https-proxy http://your-proxy-address:port
    

  • 取消不安全的NODE_TLS_REJECT_UNAUTHORIZED=0设置，若存在证书信任问题，可指定系统CA证书路径：

    export NODE_EXTRA_CA_CERTS="/etc/ssl/cert.pem" # 根据Mac实际证书路径调整
    

• 手动指定本地headers文件
  手动下载node-v20.9.0-headers.tar.gz到本地，然后通过环境变量告知node-gyp使用本地文件：

  export npm_config_node_headers="/path/to/your/downloaded/node-v20.9.0-headers.tar.gz"
  rm -rf node_modules package-lock.json
  npm install
  

• 调整node-gyp与依赖版本

  • 升级node-gyp至最新版本：

    npm install -g node-gyp@latest
    

  • 检查node-expat兼容性：Node.js 20发布后部分旧版native包可能不兼容，尝试升级node-expat到最新版，或寻找替代包。

• 修正Python版本配置
  Node.js 16+版本的node-gyp推荐使用Python 3.6及以上版本，可切换回Python 3.9.6重新尝试：

  pyenv global 3.9.6
  npm config set python $(which python3)
  rm -rf node_modules package-lock.json
  npm install
  

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