node-gyp common.gypi中'uv_library%'语法错误求助

问题复现 #

在Mac环境下执行npm install时，node-gyp解析~/.node-gyp/18.18.0/include/node/common.gypi文件报错，错误指向第一行'uv_library%': 'static_library'的语法问题，具体错误信息：

Error Message:
 File "/Users/MYNAME/.node-gyp/18.18.0/include/node/common.gypi", line 1
npm ERR!     'uv_library%': 'static_library',
npm ERR!                  ^
npm ERR! SyntaxError: invalid syntax
npm ERR! gyp ERR! configure error 
npm ERR! gyp ERR! stack Error: `gyp` failed with exit code: 1

原因分析 #

该错误并非common.gypi文件本身存在语法问题，而是node-gyp错误调用了Python 3版本解析配置文件。gypi配置文件的语法兼容Python 2，但与Python 3的语法解析规则冲突，导致触发SyntaxError。

解决方案 #

1. 强制指定node-gyp使用Python 2.7 #

• 临时生效：执行以下命令后再运行npm install

  export PYTHON=/usr/bin/python2
  npm install
  

• 永久生效：配置npm默认使用Python 2.7

  npm config set python /usr/bin/python2
  

2. 清理缓存重置环境 #

• 删除node-gyp缓存目录

  rm -rf ~/.node-gyp
  

• 清理npm缓存

  npm cache clean --force
  

• 重新执行npm install

3. 检查Xcode Command Line Tools完整性 #

Mac环境下node-gyp依赖Xcode编译工具链，执行以下命令确保工具安装完整：

xcode-select --install

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