发布后白屏了？原因查找

NnnLillian
169 阅读5分钟

前置条件，webpack打包的csr项目。首先，根据现象探究原因。

  1. 发布后白屏，本地运行时是ok的
  2. 是白屏，不是404，更像是有些方法没找到
  3. 白屏现象虽然略高频，但是偶现，并且同一时间是有的人出现，有的人没有；用户并无反馈，往往都是盯着发布的运营会发现这个问题。

根据上面三个现象，主要推断，可能是打包出的产物app.js?v=hash。出现hash值不变，但是内容产生变化的情况。提出猜想之后，先查询了有没有这种可能的情况，得知有了之后在后续的发布中就特别留意这一点，很快，就被我catch了。

之后详细查了问题原因和解法（我的原因是hash类型混淆，但是给出了其他的可能原因，应该多方向排查。

1. Webpack 的 Hash 类型混淆

Webpack 支持三种哈希策略：

  • [hash]: 基于整个构建过程生成（任意文件改动都会改变所有输出的哈希值）
    • 适用场景：几乎不推荐使用，因为一次小改动会导致所有文件哈希失效，破坏缓存优化。
  • [chunkhash]: 基于单个 chunk 内容生成（仅影响相关 chunk）
    • 只有该 Chunk 或其依赖的模块发生变化时，哈希才会变化。
    • 适用于多入口项目，但需要注意代码分割的影响。
    • 问题：如果多个 Chunk 共享某些模块（如 react），修改共享模块会导致所有相关 Chunk 的哈希变化。
  • [contenthash]: 基于文件内容生成（最精确的缓存策略）
    • 仅当文件内容实际变化时，哈希才会变化。
    • 最佳实践：适用于所有静态资源（JS、CSS、图片），是长效缓存（Long-Term Caching）的推荐方式。

常见问题：若你配置的是 [hash]，但修改了其他 chunk 的内容，理论上所有文件哈希都应变化。若哈希未变但内容变化，可能是配置了错误的哈希类型。

// webpack.config.js 错误示例（使用全局 hash）
output: {
  filename: 'app.[hash].js', // ❌ 所有文件共享同一 hash
}

// 正确做法应使用 contenthash
output: {
  filename: 'app.[contenthash].js', // ✅ 基于文件内容生成 hash
}

额外问题：那Hash就没有一点优点吗？

在大多数现代前端项目中，[contenthash] 是更优的选择，因为它能精准绑定文件内容和哈希值，实现细粒度缓存控制。但 [hash]（全局哈希） 并非完全没有价值，它仍有一些特定场景下的优势。以下是两者的对比及 [hash] 的潜在优点：

一、[hash]的核心优点

1. 强制全局缓存失效

  • 场景：当需要确保所有客户端资源 严格同步更新 时（例如修复紧急安全漏洞后，要求所有用户立即丢弃旧缓存）。
  • 机制：任何代码改动都会导致所有文件的哈希变化，无论改动是否影响具体文件。

2. 简化版本管理

  • 场景：在简单项目中，所有文件需要共享同一版本标识（如小工具、简单静态页面）。
  • 优势：无需跟踪多个哈希值，统一版本更易管理。

3. 规避边缘问题

  • 场景：当项目存在隐式依赖时（如 JS 和 CSS 文件需要严格同步加载，避免版本不一致导致样式错乱）。
  • 风险缓解：全局哈希强制所有文件同步更新，规避因部分文件未更新导致的兼容性问题。

尽管有上述优点，[hash] 的缺陷通常远大于收益。最终建议：除非有明确的全局强制更新需求，否则始终优先使用 [contenthash]。若必须使用 [hash]，建议限定在开发环境或特殊场景，并充分评估其对用户体验和成本的影响。

2. 构建环境中的变量污染

若你的代码中包含动态生成的内容（例如 Date.now()、Math.random() 或环境变量），会导致相同源码每次构建产生不同输出。

常见场景：

  • 代码中硬编码了构建时间戳
  • 未固化版本号（如 __VERSION__ = process.env.BUILD_TIME）
  • 使用非确定性插件（如某些注入调试代码的插件）
// 错误示例：代码中包含动态内容
const buildTime = Date.now(); // ⚠️ 每次构建值不同

3. 依赖版本或构建工具链不一致

  • 依赖的间接更新：package-lock.json/yarn.lock 未锁定版本，导致子依赖自动升级
  • OS/Node.js 差异：不同操作系统或 Node.js 版本可能影响构建结果（如文件路径处理）
  • Webpack 插件的不确定性：某些插件可能引入非确定性行为（例如未排序的模块 ID）

4. Webpack 配置中的非确定性因素

以下配置可能导致构建结果不一致：

  • 未指定 optimization.moduleIds：默认的 named 模式可能因文件顺序变化导致 ID 不同
  • 未排序的模块引入：如使用 require.context 加载文件时未排序文件列表

解决方案：

// webpack.config.js
optimization: {
  moduleIds: 'deterministic', // ✅ 固定模块 ID 生成算法
  chunkIds: 'deterministic',
}

🔧 排查步骤

  1. 检查哈希类型：确认 Webpack 配置使用的是 [contenthash]
  2. 锁定依赖：确保 package-lock.json/yarn.lock 提交到版本控制
  3. 对比构建产物：使用 diff 工具对比两次构建的 app.js，查找变化部分
  4. 禁用可疑插件：逐一关闭插件排查是否有工具引入动态内容
  5. 启用构建分析：使用 webpack-bundle-analyzer 观察模块变化
avatar
文章
阅读
粉丝