React项目执行npm run build时index.scss解析错误求助

问题背景 #

花了数小时排查解决方案，发现不少人遇到同类问题但无有效答案。尝试过移除grid的方法无效，也确认过项目中不存在PostCSS相关语法问题。耗时数月开发的React项目，部署时执行npm run build已卡死3小时。移除index.scss中的@import "~bootstrap/scss/bootstrap";可成功构建，但会破坏所有模板样式。需要找到无需将Sass转为标准CSS的解决办法。

版本信息 #

• sass: ^1.54.7
• react-bootstrap: ^2.5.0
• bootstrap: ^5.2.0

完整package.json #

{
  "name": "seo-workflows",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@emotion/react": "^11.10.0",
    "@emotion/styled": "^11.10.0",
    "@fortawesome/react-fontawesome": "^0.2.0",
    "@mui/icons-material": "^5.10.2",
    "@mui/material": "^5.10.2",
    "@mui/x-data-grid": "^5.16.0",
    "@pathofdev/react-tag-input": "^1.0.7",
    "@testing-library/jest-dom": "^5.14.1",
    "@testing-library/react": "^11.2.7",
    "@testing-library/user-event": "^12.8.3",
    "axios": "^0.27.2",
    "bootstrap": "^5.2.0",
    "downshift": "^6.1.9",
    "firebase": "^9.9.2",
    "react": "^17.0.2",
    "react-bootstrap": "^2.5.0",
    "react-dom": "^17.0.2",
    "react-fontawesome": "^1.7.1",
    "react-helmet": "^6.1.0",
    "react-icons": "^4.4.0",
    "react-router-dom": "^5.2.0",
    "react-scripts": "4.0.3",
    "sass": "^1.54.7",
    "web-vitals": "^1.1.2"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

可行解决方案 #

1. 降级Sass到兼容版本 #

react-scripts 4.0.3与新版Sass（1.50+）存在兼容性问题，会导致编译卡死。将Sass降级到1.49.9：

npm uninstall sass
npm install sass@1.49.9 --save-dev

该版本经大量用户验证，能和react-scripts 4.x稳定配合，且不影响Bootstrap Sass的正常编译。

2. 按需导入Bootstrap Sass模块 #

全量导入bootstrap.scss会包含大量未使用的样式，导致编译负载过高。改为只导入项目实际需要的模块：
替换index.scss中的全量导入代码：

// 先导入Bootstrap核心基础
@import "~bootstrap/scss/functions";
@import "~bootstrap/scss/variables";
@import "~bootstrap/scss/mixins";

// 按需导入组件样式，示例如下
@import "~bootstrap/scss/grid";
@import "~bootstrap/scss/buttons";
@import "~bootstrap/scss/forms";
@import "~bootstrap/scss/card";
// 根据项目需求添加其他模块

这种方式能大幅减少编译工作量，避免构建卡死，同时保留所需样式。

3. 升级react-scripts到最新稳定版 #

react-scripts 4.0.3版本较旧，升级到5.x系列可更好兼容新版Sass：

npm install react-scripts@latest --save

升级后需注意依赖兼容性（当前项目的React 17.0.2与react-scripts 5.x兼容），但能从根源解决构建工具与Sass的适配问题。

4. 禁用生产环境Source Map #

在项目根目录创建.env.production文件，添加以下配置：

GENERATE_SOURCEMAP=false

禁用Source Map生成可减少大量构建时间，尤其在导入大型Sass库时效果显著。

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