Heroku部署MERN网站构建失败 无法读取undefined的includes属性

问题背景 #

• 部署场景：Heroku平台部署MERN栈电商网站
• 触发流程：首次提示同版本代码已完成构建，重新触发构建流程后失败
• 核心报错：执行react-scripts build生成生产优化包阶段编译失败，抛出Cannot read properties of undefined (reading 'includes')错误

完整构建日志 #

-----> 构建阶段：正在运行heroku-postbuild脚本
   > ecommerce@1.0.0 heroku-postbuild
   > NPM_CONFIG_PRODUCTION=false && npm install --prefix frontend && npm run build --prefix frontend
   
   
   added 2097 packages, and audited 2098 packages in 44s
   
   161 packages are looking for funding
     run `npm fund` for details
   
   39 vulnerabilities (2 moderate, 26 high, 11 critical)
   
   To address issues that do not require attention, run:
     npm audit fix
   
   To address all issues (including breaking changes), run:
     npm audit fix --force
   
   Run `npm audit` for details.
   
   > frontend@0.1.0 build
   > react-scripts build
   
   Creating an optimized production build...
   Failed to compile.
   
   Cannot read properties of undefined (reading 'includes')
   
-----> 构建失败
   构建失败可参考平台官方排查文档，或提交工单联系Heroku技术支持。
   
! 推送被拒绝，Node.js应用编译失败
! 推送失败

排查解决步骤 #

• 本地前置校验：进入frontend目录，本地直接执行npm run build，确认报错是否可复现。绝大多数编译阶段错误本地可直接复现，无需优先排查Heroku平台侧问题。
• 定位undefined调用点：全局搜索前端代码中所有.includes(调用位置，重点核对调用includes的变量是否存在未定义场景：
  • 优先排查环境变量相关逻辑：react-scripts仅会识别REACT_APP_前缀的自定义环境变量，未加前缀、未在Heroku配置面板中添加的环境变量，构建阶段取值为undefined，直接调用includes就会触发该报错，所有环境变量调用前加空字符串兜底即可修复，示例写法：(process.env.REACT_APP_BASE_API || '').includes('/api')
  • 其次排查路由、权限判断逻辑：检查react-router相关的路径判断、用户角色权限判断代码，确认调用includes的路径值、角色值不存在空值场景，必要时加可选链和兜底值。
• 修复依赖兼容问题：如果全局搜索未找到业务代码中的问题点，删除frontend目录下的node_modules文件夹与package-lock.json文件，重新执行npm install后再次本地build。旧版本react-scripts与高版本Node.js运行时存在已知兼容问题，可在项目根目录package.json中添加engines字段，指定与本地开发一致的Node、npm版本，避免Heroku拉取不兼容的默认版本：

"engines": {
  "node": "18.x",
  "npm": "9.x"
}

• 清理平台构建缓存：如果本地build完全正常，仅Heroku环境报错，安装Heroku CLI的builds插件后清理构建缓存，再重新推送代码触发构建：

heroku plugins:install heroku-builds
heroku builds:cache:purge -a 你的Heroku应用名称

注意：npm audit提示的依赖漏洞不影响构建流程，无需优先处理该部分提示。

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