基于CoreUI React模板的网站在iPhone12全浏览器中卡顿或白屏求助

开发者阿泽

2026-7-18

iPhone12 浏览器中 CoreUI React 4.0 模板网站卡顿/滚动白屏问题排查方案

我基于CoreUI React 4.0免费模板搭建网站，遇到以下问题：

iPhone12 上所有主流浏览器（Safari、Chrome、Firefox、Edge）均会时常出现完全卡顿（无法滚动或点击）或滚动后页面下半部分白屏的情况
iOS 及所有浏览器已更新至最新版本，设备访问其他网站正常
iPhone13/14、Windows/macOS 桌面设备、Android 设备访问该网站无异常
后端采用 Laravel Lumen 构建

附上项目配置文件：

package.json

{
  "name": "@coreui/coreui-free-react-admin-template",
  "version": "4.0.0",
  "description": "CoreUI Free React Admin Template",
  "homepage": ".",
  "bugs": {
    "url": "https://github.com/coreui/coreui-free-react-admin-template/issues"
  },
  "repository": {
    "type": "git",
    "url": "git@github.com:coreui/coreui-free-react-admin-template.git"
  },
  "license": "MIT",
  "author": "The CoreUI Team (https://github.com/orgs/coreui/people)",
  "scripts": {
    "build": "react-scripts build",
    "changelog": "auto-changelog --starting-version 3.0.0 --commit-limit false --hide-credit",
    "eject": "react-scripts eject",
    "lint": "eslint \"src/**/*.js\"",
    "start": "react-scripts start",
    "test": "react-scripts test",
    "test:cov": "npm test -- --coverage --watchAll=false",
    "test:debug": "react-scripts --inspect-brk test --runInBand"
  },
  "config": {
    "coreui_library_short_version": "4.0"
  },
  "dependencies": {
    "@coreui/chartjs": "^3.0.0",
    "@coreui/coreui": "^4.0.5",
    "@coreui/icons": "^2.1.0",
    "@coreui/icons-react": "2.0.0",
    "@coreui/react": "4.0.0",
    "@coreui/react-chartjs": "2.0.0",
    "@coreui/utils": "^1.3.1",
    "@wojtekmaj/enzyme-adapter-react-17": "^0.6.3",
    "chart.js": "^3.5.1",
    "classnames": "^2.3.1",
    "core-js": "^3.18.3",
    "downloadjs": "^1.4.7",
    "enzyme": "^3.11.0",
    "formik": "^2.2.9",
    "generate-password": "^1.7.0",
    "match-sorter": "^6.3.1",
    "prettier": "^2.4.1",
    "prop-types": "^15.7.2",
    "react": "^17.0.2",
    "react-app-polyfill": "^2.0.0",
    "react-datepicker": "^4.3.0",
    "react-dom": "^17.0.2",
    "react-redux": "^7.2.5",
    "react-router-dom": "^5.3.3",
    "react-select": "^5.7.1",
    "react-select-search": "^4.1.6",
    "react-table": "^7.7.0",
    "redux": "4.1.1",
    "simplebar-react": "^2.3.6",
    "yup": "^1.0.2"
  },
  "devDependencies": {
    "auto-changelog": "~2.3.0",
    "eslint": "^7.32.0",
    "eslint-config-prettier": "^8.3.0",
    "eslint-plugin-prettier": "^4.0.0",
    "react-scripts": "^4.0.3",
    "sass": "^1.43.2"
  },
  "engines": {
    "node": ">=10",
    "npm": ">=6"
  }
}

.browserslistrc

# https://github.com/browserslist/browserslist#readme

>= 0.5%
last 2 major versions
not dead
Chrome >= 60
Firefox >= 60
Firefox ESR
iOS >= 12
Safari >= 12
not Explorer <= 11

排查与修复方案

1. 修复 simplebar-react 兼容性问题

项目中使用的 simplebar-react@2.3.6 在iPhone12搭载的iOS版本（含更新后）中存在滚动渲染冲突，易引发卡顿或白屏：

升级到最新稳定版：
```
npm install simplebar-react@latest
```

若升级无效，添加CSS强制启用iOS原生滚动优化：

.simplebar-content-wrapper {
  -webkit-overflow-scrolling: touch !important;
  overflow-scrolling: touch !important;
}

2. 优化React组件渲染性能

iPhone12的浏览器对高频重渲染的承载能力有限，需针对性优化：

用React DevTools的Profiler工具定位频繁重渲染的组件，通过React.memo、useMemo或useCallback减少不必要更新

对页面中的图表组件（chart.js/@coreui/react-chartjs）采用懒加载：

import { lazy, Suspense } from 'react';
const ChartComponent = lazy(() => import('./ChartComponent'));

// 使用组件时
<Suspense fallback={<div>加载中...</div>}>
  <ChartComponent />
</Suspense>

3. 调整browserslist适配iOS 14+

当前配置iOS >=12覆盖范围过广，导致编译代码未针对iPhone12的iOS版本做优化：

修改.browserslistrc为：

>= 0.5%
last 2 major versions
not dead
Chrome >= 60
Firefox >= 60
Firefox ESR
iOS >= 14
Safari >= 14
not Explorer <= 11

重新构建项目：
```
npm run build
```

4. 升级CoreUI相关依赖

@coreui/react@4.0.0为早期版本，存在iOS特定渲染bug：

升级至4.x最新稳定版：

npm install @coreui/coreui@latest @coreui/react@latest @coreui/icons-react@latest

5. 解决Safari弹性滚动冲突

iPhone12的Safari弹性滚动可能与自定义滚动逻辑冲突：

在public/index.html中更新viewport标签：

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover, user-scalable=no">

或添加CSS限制滚动行为：

body {
  overscroll-behavior: contain;
}

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