React/SPFx项目执行gulp bundle --ship编译失败求助

问题详情 #

我有一个React/SPFx项目无法完成编译，当前使用Node版本为18.18.2，执行gulp bundle --ship命令时出现编译错误。已尝试切换Node 16.X、14.X版本，也重新安装过node_modules，但问题依旧。

项目的package.json配置如下：

{
  "name": "project-name",
  "version": "0.0.1",
  "private": true,
  "engines": {
    "node": ">=16.13.0 <17.0.0 || >=18.17.1 <19.0.0"
  },
  "main": "lib/index.js",
  "scripts": {
    "build": "gulp bundle",
    "clean": "gulp clean",
    "test": "gulp test"
  },
  "dependencies": {
    "@fluentui/react": "^8.106.4",
    "@microsoft/rush-stack-compiler-4.5": "^0.5.0",
    "@microsoft/sp-component-base": "1.18.0",
    "@microsoft/sp-core-library": "1.18.0",
    "@microsoft/sp-lodash-subset": "1.18.0",
    "@microsoft/sp-office-ui-fabric-core": "1.18.0",
    "@microsoft/sp-property-pane": "1.18.0",
    "@microsoft/sp-webpart-base": "1.18.0",
    "@pnp/spfx-controls-react": "^3.15.0",
    "jquery": "^3.7.1",
    "moment": "^2.29.4",
    "office-ui-fabric-react": "^7.204.0",
    "react": "17.0.1",
    "react-dom": "17.0.1",
    "tslib": "2.3.1"
  },
  "devDependencies": {
    "@microsoft/eslint-config-spfx": "1.18.0",
    "@microsoft/eslint-plugin-spfx": "1.18.0",
    "@microsoft/rush-stack-compiler-4.7": "0.1.0",
    "@microsoft/sp-build-web": "1.18.0",
    "@microsoft/sp-module-interfaces": "1.18.0",
    "@rushstack/eslint-config": "2.5.1",
    "@types/react": "17.0.45",
    "@types/react-dom": "17.0.17",
    "@types/webpack-env": "1.18.2",
    "ajv": "^6.12.5",
    "eslint": "8.7.0",
    "eslint-plugin-react-hooks": "4.3.0",
    "gulp": "^4.0.2",
    "typescript": "4.7.4"
  }
}

解决步骤 #

1. 统一Rush Stack Compiler版本 #

项目依赖中同时存在@microsoft/rush-stack-compiler-4.5（dependencies）和@microsoft/rush-stack-compiler-4.7（devDependencies），版本不一致会导致编译工具链冲突。将dependencies中的版本修改为与devDependencies一致：

// 修改dependencies中的对应项，删除原4.5版本条目
"@microsoft/rush-stack-compiler-4.7": "0.1.0"

2. 移除冲突的UI库依赖 #

同时安装@fluentui/react@8.x和office-ui-fabric-react@7.x会导致类型定义冲突和编译错误，二者为同一UI库的不同大版本，只能保留其一：

• 若使用Fluent UI v8：删除office-ui-fabric-react依赖，确保代码中组件导入均来自@fluentui/react；
• 若保留Office UI Fabric v7：删除@fluentui/react依赖，调整代码适配v7组件。

3. 彻底清理并重装依赖 #

执行以下命令清除旧依赖和缓存：

gulp clean
rm -rf node_modules package-lock.json
npm install

如果使用yarn，替换为rm -rf node_modules yarn.lock && yarn install。

4. 确认Node版本兼容性 #

项目engines字段指定Node版本范围为>=16.13.0 <17.0.0 || >=18.17.1 <19.0.0，当前18.18.2符合要求。建议使用nvm工具管理Node版本，避免全局版本干扰：

nvm use 18.18.2

完成上述步骤后，重新执行gulp bundle --ship即可正常编译。

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