在使用 Webpack 做生产构建时，几乎所有项目都会在输出文件名里加上哈希值，比如 app.3f5a2b.js 这种形式。哈希值的作用是让浏览器能够利用强缓存，文件内容不变时文件名不变，命中缓存；内容一变文件名跟着变，缓存自动失效。不知道你有没有注意过，这个哈希串的长度其实是可以控制的，控制它的就是 output.hashDigestLength。这个配置虽然小，但在缓存策略、日志排查、产物管理等场景里都有实际影响，值得单独拿出来讲清楚。
hashDigestLength 是什么，它控制的是哪一段
先明确概念。Webpack 生成哈希的过程中有三个相关配置：hashFunction 决定用什么哈希算法，默认是 md4（新版本中默认为 xxhash64）；hashDigest 决定摘要的编码方式，默认是 hex 十六进制；hashDigestLength 决定最终截取多少个字符作为哈希串，默认是 20。
也就是说，无论底层算法算出的摘要有多长，md4 的摘要原始长度是 128 位，hex 编码后是 32 个字符，最终文件名里出现的哈希，只是这个 32 字符摘要的前 hashDigestLength 个字符。默认取 20 位，但你可以根据需要改成 8 位、16 位甚至 32 位。这个截取逻辑理解了，后面的取舍分析就很好懂了。
需要区分的一点是，output.hashDigestLength 影响的是所有哈希占位符的输出长度，包括 [hash]、[contenthash] 和 [chunkhash]，它是一个全局长度控制，而不是针对某一个占位符单独设置的。如果你只想让某个占位符使用不同长度，可以在占位符后面加冒号指定，例如 [contenthash:8]，这种写法优先级高于全局配置。
如何配置以及不同长度下的实际效果
配置方式很直接，写在 output 对象里即可。下面是一个典型例子：
const path = require('path');
module.exports = {
entry: './src/index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'js/[name].[contenthash:16].js',
// 全局哈希摘要长度，默认 20
hashDigestLength: 16,
// 可选：指定哈希算法
// hashFunction: 'xxhash64',
// 可选：指定摘要编码
// hashDigest: 'base64'
}
};执行构建后，如果代码内容没有变化，输出的文件名会稳定为 js/main.3f5a2b1c9d8e7f60.js 这样的形式。把 hashDigestLength 改成 8，文件名就变成 js/main.3f5a2b1c.js。改成 32，则会把整个 md4 hex 摘要完整输出。注意上面配置里同时用了 [contenthash:16] 和 hashDigestLength: 16，占位符局部指定会覆盖全局值，实际生效的是 16。如果占位符写成 [contenthash]，则跟随全局配置。
还有一个容易被忽略的细节：如果 hashDigest 改成了 base64，可选字符集变成 64 个，同样长度下能表达的信息量更大。比如 base64 编码下取 16 位，等效的碰撞概率要低于 hex 编码 16 位。不过 base64 输出可能包含 +、/、= 等字符，用在 URL 里需要谨慎，一般还是建议保持默认的 hex。
长度取多少合适：碰撞概率与工程权衡
哈希长度本质上是在碰撞概率和文件名可读性之间做权衡。hex 编码下每一位有 16 种可能，取 N 位就是 16 的 N 次方种组合。取 8 位约有 42 亿种组合，取 16 位约 1800 亿亿种，取 20 位默认值则超过 10 的 24 次方。对于一个项目来说，需要比较的是所有历史构建产物之间的碰撞，如果项目迭代非常频繁、构建次数以万计，8 位确实存在极低的碰撞风险，一旦碰撞，两个内容不同的文件会共用同一个文件名，导致 CDN 缓存串文件，这是很难排查的线上事故。
实践中比较常见的取值有两档。一是 8 位，文件名短、日志里看着清爽，CDN 地址也更短，适合中小型项目或者使用 [contenthash:8] 的团队规范。二是保持默认的 20 位或者取 16 位，几乎可以完全忽略碰撞，适合大型项目、多团队共用构建流水线的场景。另外在结合 splitChunks 拆分大量异步 chunk 的项目里，chunk 数量可能达到几百个，此时产物之间的比较基数变大，建议至少保留 16 位。
开发环境则完全不必纠结，由于 webpack-dev-server 使用内存文件系统，文件名根本不会落盘，通常开发环境直接去掉哈希或使用默认值即可，把调整重心放在生产环境的缓存策略上。同时记得开启 optimization.realContentHash（Webpack 5 默认开启），它保证哈希真正反映文件内容自身，避免因为模块 ID 变化导致内容没变但哈希变了的情况，这对缓存命中率的影响远大于哈希长度本身。
常见问题与注意事项
第一个坑是哈希长度改了之后缓存全失效。因为文件名变了，所有引用该文件的 HTML 也要重新生成，这是正常现象，但在灰度发布时要注意新旧文件名共存期间的 CDN 存储占用，定期清理过期的历史构建产物是必要的运维配套。
第二个坑是与运行时代码的关联。chunk 之间的引用关系是通过 runtime 里的文件名映射维护的，如果使用了 optimization.runtimeChunk 抽离运行时，修改 hashDigestLength 后务必做一次完整构建，不要把增量构建的产物和旧产物混在一起部署，否则会出现运行时按旧文件名去加载 chunk 导致 404 的问题。
最后，如果你使用的是 Vite 或 Rspack 等新一代工具，虽然配置项名称不同，但思路一致：Vite 中对应的是 build.rollupOptions.output.hashCharacters 相关的长度控制写法（通常直接在文件名模板里写 .[hash:8]），Rspack 则完整兼容 output.hashDigestLength。理解了截取摘要前 N 位这个底层逻辑，换任何构建工具都能快速上手对应的配置。
WebpackhashDigestLength哈希摘要修改时间：2026-09-15 04:22:31