Webpack 构建产物里的那串神秘哈希值，比如 main.a8f3c2e1b9d4.js，相信每个前端开发者都见过。但很少有人去追究这串值是怎么算出来的。实际上，Webpack 在计算模块哈希、chunk 哈希以及最终文件名哈希时，都依赖一个核心配置项——output.hashFunction。它决定了底层使用的哈希算法，默认值是 md4 的替代方案（新版本已默认使用 xxhash64 或 md4 polyfill），但在一些对安全或跨环境一致性有要求的场景下，你会需要手动把它改成 md5、sha1 或 sha256。这篇文章就来把这个配置讲透。
一、hashFunction 到底控制什么
先明确概念。Webpack 内部有多个与哈希相关的输出字段：[hash] 代表整个编译的哈希，[chunkhash] 代表单个 chunk 的哈希，[contenthash] 则根据提取出的文件内容（通常是 CSS）计算。output.hashFunction 影响的是这三个字段背后的计算算法，也就是说，一旦你修改它，所有产物文件名里的哈希值都会随之改变。
基础配置方式如下：
const path = require('path');
module.exports = {
entry: './src/index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: '[name].[contenthash:8].js',
// 关键配置：指定哈希算法
hashFunction: 'sha256',
// 通常配合使用的两项
hashDigest: 'hex',
hashDigestLength: 8
}
};这里还有两个容易混淆的配套选项要说明一下。hashDigest 指定哈希摘要的编码格式，可选值有 hex、base64、base36 等，默认是 hex；hashDigestLength 决定最终截取多少位字符拼进文件名。也就是说，你在文件名里看到的那 8 位哈希，其实是 sha256（或 md5 等）算出的完整摘要的前 8 个字符。截断会让碰撞概率上升，8 位 hex 字符是 32 bit，配合内容寻址场景一般够用，但如果你的项目产物数量达到数千个，建议放到 12 位以上。
另外一个细节：从 Webpack 5 某些小版本开始，Node.js 移除了内置的 md4 支持（因为 OpenSSL 3 默认禁用了弱哈希算法），官方提供了 wasm 版 md4 polyfill 来兜底，但这会带来额外的依赖下载和轻微的性能开销。这就是很多团队主动把 hashFunction 改成 md5 或 xxhash64 的直接原因。
二、md5、sha1、sha256 三种算法横向对比
这三种算法都是经典的加密哈希函数，但特性差异明显。下面从三个维度来比较。
第一是计算速度。md5 和 sha1 的运算轮数少，理论上比 sha256 快一些。不过在现代构建场景中，哈希计算的耗时占比其实很小，瓶颈更多在于代码压缩和文件 IO。真正追求极致构建速度的话，应该选择非加密哈希 xxhash64，它专为内容寻址设计，速度是 md5 的数倍，而且碰撞分布对构建场景完全够用。Webpack 5 中可以直接这样写：
module.exports = {
output: {
path: path.resolve(__dirname, 'dist'),
filename: '[name].[contenthash:8].js',
// xxhash64 需要 webpack 5.54+ 版本支持
hashFunction: 'xxhash64'
}
};第二是安全强度。md5 和 sha1 都已被密码学界证明存在实际碰撞攻击，攻击者可以构造出两个内容不同但哈希相同的数据。而 sha256 属于 SHA-2 家族，目前没有已知的实用碰撞攻击。如果你所在的团队执行供应链安全规范，或者安全扫描工具会检查构建配置，直接选择 sha256 是最省事的做法，能一次性消除告警。
第三是摘要长度。md5 输出 128 bit，sha1 输出 160 bit，sha256 输出 256 bit。在配合 hashDigestLength 截断的前提下，这个差异主要体现在理论上限。下面这张表汇总了核心区别：
| 算法 | 摘要长度 | 相对速度 | 碰撞安全 | 适用场景 |
|---|---|---|---|---|
| md5 | 128 bit | 快 | 已被破解，存在碰撞攻击 | 旧项目兼容、无安全审计要求 |
| sha1 | 160 bit | 较快 | 已被破解（SHAttered 攻击） | 不推荐新项目使用 |
| sha256 | 256 bit | 中等 | 安全 | 有安全合规要求的项目 |
| xxhash64 | 64 bit | 极快 | 非加密哈希，碰撞概率极低 | 追求构建性能的大型项目 |
三、自定义哈希函数与常见坑
hashFunction 除了接受算法名字符串，还可以直接传入一个函数。这个函数需要返回一个对象，该对象实现 update 和 digest 两个方法，接口和 Node.js 的 crypto.createHash 返回的对象保持一致。自定义函数最常见的用途是接入公司内部的哈希规范，或者在不支持某些算法的 Node 版本上做降级处理。
const crypto = require('crypto');
module.exports = {
output: {
filename: '[name].[contenthash:8].js',
hashFunction: () => {
return {
update(data) {
this._data = (this._data || '') + data;
return this;
},
digest(type) {
return crypto
.createHash('sha256')
.update(this._data)
.digest(type);
}
};
}
}
};使用时有几个坑需要提醒。第一，修改 hashFunction 后，所有产物的哈希都会变化，如果你的 CI 流水线依赖固定哈希做缓存校验（比如 Docker 镜像分层、CDN 预热白名单），需要同步更新策略，否则会出现一波全量刷新。第二，跨机器构建结果不一致的问题，往往不是算法本身，而是模块顺序或路径差异导致的，此时应该配合 output.hashSalt 加盐，并检查是否有绝对路径被打进依赖图。第三，xxhash64 这类非加密哈希虽然快，但不要用在任何涉及签名、防篡改校验的场景，它只解决内容寻址问题，不提供安全保证。
最后给一个简单的选型结论：普通业务项目直接用默认值或切到 xxhash64 获得更快的构建速度；金融、政务等有合规审计要求的项目用 sha256；md5 只在维护老项目时保留，sha1 则不建议再出现在任何新配置里。理解了 hashFunction、hashDigest、hashSalt 三者的关系，你就能对构建产物的稳定性做到完全掌控。
Webpack配置hashFunction哈希函数修改时间：2026-09-07 10:10:45