Chrome 安装 React App 时白屏如何解决？

Question

在使用 Chrome 浏览器以 PWA 方式安装 React 应用时，常出现白屏问题。该问题多因生产环境构建路径配置错误导致静态资源加载失败。典型表现为：应用安装后首次打开显示空白页面，但直接访问网页正常。检查 `public/index.html` 中的资源引用路径及 `package.json` 的 `homepage` 字段是否正确设置（如设为 `"."` 或对应部署路径），并确保 `build` 阶段生成的资源路径为相对路径。此外，Service Worker 缓存异常也可能引发白屏，可尝试清除缓存或更新 `sw-precache` 配置。

Answer 1

一、PWA 白屏问题的常见现象与初步排查

在使用 Chrome 浏览器以 PWA（Progressive Web App）方式安装 React 应用时，开发者常遇到“白屏”问题。该现象表现为：应用通过“添加到主屏幕”安装后首次打开为空白页面，但直接在浏览器中访问 URL 却能正常加载。

初步判断此类问题通常源于生产环境构建阶段的资源路径配置错误，导致静态资源（如 JS、CSS、图片等）无法正确加载。以下是常见的排查点：

• 检查 public/index.html 中的资源引用是否为相对路径
• 确认 package.json 中的 homepage 字段设置正确
• 验证构建输出的 build/ 目录中资源路径是否合理
• 查看浏览器开发者工具中的 Network 面板是否存在 404 错误

二、深入分析：构建路径与资源引用机制

React 应用默认使用 Create React App（CRA）进行构建，其打包过程依赖于 Webpack 配置。当未正确设置部署上下文路径时，生成的资源路径可能为绝对根路径（如 /static/js/main.123.js），而 PWA 安装后运行环境可能并非部署在域名根目录下，导致请求失败。

关键配置项如下表所示：

配置项	作用	推荐值（子路径部署）	推荐值（根路径部署）
homepage in package.json	指定公共路径前缀	"./" 或 "/myapp"	"." 或 "http://example.com"
%PUBLIC_URL% in index.html	动态注入公共路径	自动适配 homepage	同上
publicPath in Webpack (ejected)	控制资源基础路径	./	/

三、Service Worker 缓存异常的影响与调试

PWA 的核心特性之一是离线能力，依赖于 Service Worker（SW）缓存资源。若 SW 缓存了错误版本或过期的 HTML 文件，即使路径已修复，用户仍可能加载旧缓存导致白屏。

可通过以下步骤清除并验证缓存行为：

1. 打开 Chrome DevTools → Application → Clear storage → Clear site data
2. 进入 Application → Service Workers → 点击 Unregister 或 Check "Update on reload"
3. 重新构建并部署应用，确保 sw-precache 或 Workbox 配置正确
4. 检查 precache-manifest*.js 文件中缓存的资源路径是否为相对路径

示例 Workbox 配置片段（src/service-worker.js）：

import { precacheAndRoute } from 'workbox-precaching';

// 动态获取 webpack 注入的预缓存列表
precacheAndRoute(self.__WB_MANIFEST, {
  ignoreURLParametersMatching: [/^utm_/, /^fbclid$/]
});
  

四、构建流程与路径处理的底层机制

当执行 npm run build 时，CRA 会根据 homepage 字段决定资源的公共路径（public path）。若设置为 "." 或 "./"，则所有资源将使用相对路径；若留空或为绝对路径，则使用 / 作为前缀。

Mermaid 流程图展示构建路径决策逻辑：

graph TD
      A[开始构建] --> B{homepage 是否设置?}
      B -- 是 --> C[解析 homepage 值]
      B -- 否 --> D[默认使用 "/"]
      C --> E{值为 "." 或 "./"?}
      E -- 是 --> F[设置 publicPath 为 "./"]
      E -- 否 --> G[设置 publicPath 为 homepage 全路径]
      F --> H[生成相对路径资源]
      G --> I[生成绝对路径资源]
      H --> J[输出 build 目录]
      I --> J

五、综合解决方案与最佳实践

为彻底解决 PWA 白屏问题，建议遵循以下步骤：

• 在 package.json 中明确设置："homepage": "."
• 确保 public/index.html 使用 %PUBLIC_URL% 引用资源，例如：
  <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
• 避免 eject 除非必要，优先使用 CRA 提供的路径机制
• 部署时确保服务器支持 History API fallback（SPA 路由）
• 在 CI/CD 中加入路径校验脚本，防止误提交错误配置
• 启用 Source Map 并监控 Sentry 或类似工具捕获客户端异常
• 定期更新 Workbox 版本，避免已知缓存 bug
• 测试阶段模拟 PWA 安装场景，使用 Lighthouse 进行完整性检测
• 对老版本 Android Chrome 特别关注，因其对相对路径处理存在兼容性问题
• 记录构建日志中的 publicPath 输出，便于回溯问题