安装React依赖时node-gyp报错：common.gypi字符串字面量EOL错误

错误原因 #

你遇到的SyntaxError: EOL while scanning string literal错误，直接原因是~/.node-gyp/20.0.0/include/node/common.gypi文件损坏——首行仅残留erate ',这类不完整的语法片段。这类文件损坏通常由以下情况导致：

• Node.js安装过程中断或不完整
• 磁盘写入异常（如磁盘空间不足、IO错误）
• 之前的npm/node-gyp操作意外终止，导致头文件下载不完整

排查修复步骤 #

1. 删除损坏的node-gyp缓存目录
   node-gyp会在~/.node-gyp存储Node版本对应的头文件，直接删除整个目录让它重新生成：

   rm -rf ~/.node-gyp
   

2. 清理npm缓存
   避免缓存的损坏依赖包干扰重新安装：

   npm cache clean --force
   

3. 重置项目依赖文件
   删除项目本地的依赖目录和锁文件，确保重新拉取干净的依赖：

   rm -rf node_modules package-lock.json
   

4. 重新执行依赖安装
   重新运行npm i，此时node-gyp会自动下载对应Node版本的完整头文件，重新编译需要native扩展的依赖。

Node.js版本建议 #

Node.js 20.0.0是20.x大版本的首个发布版本，通常存在未修复的边缘问题。建议升级到20.x分支的稳定版（比如最新的20.17.0），或者切换到长期支持（LTS）分支（如18.x、20.x的LTS版本），这类版本经过更多测试，兼容性和稳定性更有保障，能减少这类意外的文件损坏或兼容性问题。

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