运行npm link时出现npm ERR! gyp ERR! TypeError错误的求助

执行npm link felca-runtime时触发构建失败，核心错误如下：

gyp ERR! stack TypeError: Cannot assign to read only property 'cflags' of object '#<Object>'

已尝试更新npm、node-gyp、Python，清理npm缓存，但问题仍未解决。
当前环境：Node v20.7.0、npm 10.1.0、node-gyp v9.4.0、Python 3.9.6、macOS 13.5.2

该问题根源在于node-sass已停止维护，不兼容Node.js 16+版本，同时项目依赖的旧版node-gyp（v7.1.2）与Node.js 20存在兼容性冲突。以下是针对性解决步骤：

1. 替换node-sass为sass（官方推荐方案） #

node-sass已废弃，官方建议使用dart-sass（包名sass）替代：

• 卸载项目中的node-sass：

  npm uninstall node-sass
  

• 安装sass：

  npm install sass --save-dev
  

• 更新项目中所有引用node-sass的配置文件（如webpack配置、vue.config.js等），将依赖替换为sass，示例：

  // 旧配置
  loader: 'sass-loader',
  options: {
    implementation: require('node-sass')
  }
  // 新配置
  loader: 'sass-loader',
  options: {
    implementation: require('sass')
  }
  

2. 强制项目使用全局更新后的node-gyp #

项目依赖的node-gyp@7.1.2不兼容Node.js 20，可强制使用全局已更新的node-gyp：

• 删除本地依赖和锁文件：

  rm -rf node_modules package-lock.json
  

• 设置npm配置指定全局node-gyp路径：

  npm config set node_gyp "/usr/local/lib/node_modules/node-gyp/bin/node-gyp.js"
  

• 重新安装依赖：

  npm install
  

3. 降级Node.js版本（临时兼容方案） #

若无法替换node-sass，可降级Node.js至16.x（node-sass最后支持的版本）：

• 使用nvm切换版本：

  nvm install 16
  nvm use 16
  

• 清理缓存并重新安装：

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

4. 临时修复node-gyp只读属性问题（hack方案） #

若必须保留现有依赖，可手动修改项目中node-gyp的代码：

• 找到文件：/Users/theo.hodges/accelerate/felca-nhsuk/node_modules/node-gyp/lib/configure.js
• 定位到第117行，将直接赋值cflags的代码改为使用Object.assign：

  // 旧代码
  obj.cflags = ...;
  // 新代码
  Object.assign(obj, { cflags: ... });
  

• 重新执行npm link felca-runtime

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