Webpack 5 新特性之 Verifiable Credentials 可验证凭证是什么以及如何应用

Verifiable Credentials 原本是 W3C 提出的一种机器可验证的数字凭证标准，用来证明某个实体具备某种资质或拥有某份数据。在 Webpack 5 的语境下，它并不是官方文档里直接提供的一个配置项，而是社区利用 Webpack 5 的持久化缓存、内容哈希以及插件机制，构建出的一种“模块级可信证明”思路。简单来说，就是给打包出来的每一个资源或者每一段源码附加一份可以离线校验的凭证，证明它来自可信的构建源且未被中途修改。

过去我们在前端项目里依赖 package-lock.json 或者 yarn.lock 来保证依赖版本一致，但这只能约束安装阶段。一旦代码进入构建流水线，或者私有 npm 包在内部镜像中被替换，锁文件就无能为力了。Webpack 5 的模块哈希本身已经具备内容寻址特性，同样的内容永远得到同样的 hash，这其实就是一种基础的“自描述凭证”。在其之上，我们通过插件注入签名逻辑，就能把哈希升级为带有发布者身份的可验证凭证。

Webpack 5 底层机制如何支撑凭证生成

Webpack 5 引入了基于文件系统的持久化缓存，默认会将编译中间结果存放在 node_modules/.cache/webpack 目录中。这些缓存以内容哈希命名，意味着只要源文件或 loader 配置发生任何字节变化，缓存键就会改变。这种内容寻址能力是构建可验证凭证的基石，因为它保证了“凭证所对应的内容”是确定且唯一的。相比 Webpack 4 每次全量读取磁盘，5 的缓存让凭证计算可以增量进行，不会明显拖慢构建。

在 compilation 对象的 hooks 中，Webpack 5 提供了更为细粒度的生命周期点，例如 processAssets 阶段允许我们在资源写入硬盘前对其做最后一次处理。我们可以在此时读取资源的 source 内容，使用 Node 的 crypto 模块计算摘要，再用预先配置好的私钥生成签名，并将签名作为同源的 .sig 文件输出。由于整个过程发生在模块图已经解析完毕之后，所以凭证能够覆盖经过 babel、ts 等 loader 转译后的真实产物。

另外一个关键点在于 Webpack 5 的 module 对象暴露了更多元信息。通过 module.buildInfo 或 module.issuer，插件可以追溯一个模块是由哪个入口或哪个远程包引入的。这为凭证添加了“上下文维度”，例如我们可以规定来自内部 gitlab 私有源的模块必须使用 A 密钥签名，而第三方开源库使用 B 密钥。这种基于来源的策略比单纯的全量签名更贴近企业安全合规场景。

从零编写一个可验证凭证插件

下面示例展示了一个最简化的 Webpack 5 插件，它在 emit 之前为每一个 js 资源生成 SHA256 摘要，并使用 RSA 私钥签名。实际生产中你可以把公钥分发给校验服务，构建产物被部署到 CDN 后，边缘节点或浏览器扩展就能验签。

const crypto = require('crypto');
const fs = require('fs');
const path = require('path');

class VerifiableCredentialPlugin {
  constructor(options) {
    // 传入私钥路径与输出目录
    this.privateKey = fs.readFileSync(options.privateKeyPath, 'utf8');
    this.outDir = options.outDir;
  }

  apply(compiler) {
    const { webpack } = compiler;
    const { Compilation } = webpack;
    // 在资源处理阶段插入逻辑
    compiler.hooks.thisCompilation.tap('VerifiableCredentialPlugin', (compilation) => {
      compilation.hooks.processAssets.tap(
        {
          name: 'VerifiableCredentialPlugin',
          stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE
        },
        (assets) => {
          for (const filename of Object.keys(assets)) {
            if (!filename.endsWith('.js')) continue;
            const source = assets[filename].source();
            const hash = crypto.createHash('sha256').update(source).digest('hex');
            const signer = crypto.createSign('RSA-SHA256');
            signer.update(hash);
            signer.end();
            const signature = signer.sign(this.privateKey, 'base64');
            // 将凭证写为独立文件
            const credName = filename + '.vc.json';
            const credContent = JSON.stringify({
              file: filename,
              hash: hash,
              signature: signature,
              issuer: 'build-pipeline-001'
            });
            compilation.emitAsset(credName, new webpack.sources.RawSource(credContent));
          }
        }
      );
    });
  }
}

module.exports = VerifiableCredentialPlugin;

上述代码里，我们使用 compiler.hooks.thisCompilation 拿到当前编译实例，再挂到 processAssets 钩子上。这里需要注意 Webpack 5 的 assets 是只读的，必须通过 emitAsset 方法新增文件，而不能直接修改原有 assets 对象。生成的 .vc.json 文件中包含了文件哈希与签名，任何拿到公钥的人都可以用 crypto.createVerify 校验哈希是否被篡改。

在团队协作时，私钥应仅存放在 CI 机器的环境变量或密钥仓库中，开发者本地构建可以不开启签名以加快速度。校验脚本则可以集成到部署流水线，若发现某个 js 文件没有对应凭证，或者凭证验签失败，就阻断发布。这种机制比人工 code review 更能防范依赖投毒攻击。

可验证凭证与现有安全方案的对比

不少人会把 Webpack 5 的这种做法和 Subresource Integrity（SRI）混淆。SRI 是在 HTML 的 <script> 标签上写死 integrity 属性，浏览器加载时比对哈希，它防的是 CDN 被劫持。而我们在 Webpack 里生成的凭证是构建期的产物，它不仅包含哈希，还包含发布者签名，可以在服务端、网关、甚至内部审计系统中使用，不依赖浏览器支持。二者可以叠加：构建出凭证，同时根据凭证里的哈希自动生成 SRI 属性。

另一个常见方案是使用 cosign 等镜像签名工具，但那是针对容器镜像的。前端静态资源往往直接走对象存储，缺乏统一的签名体系。Webpack 插件方案的优势是零额外基础设施，只要 Node 环境就能跑。缺点则是凭证文件本身也需要被保护，如果攻击者能同时替换 js 和 .vc.json，验签就会失效，因此通常要把凭证索引放到独立的鉴权服务中。

从落地成本看，中小团队可以先只对核心业务包开启凭证，不必全量覆盖。配合 Webpack 5 的 splitChunks 功能，把第三方库和业务代码分开签名，既能控制计算量，又能在出现安全事件时快速定位是哪一类模块出了问题。长远来看，当前端供应链攻击越来越频繁，这种构建期的可验证凭证会成为基础配置而非可选项。

Webpack_5Verifiable_Credentials模块打包修改时间：2026-08-19 02:06:33