在 HTTPS 环境下使用 crypto.randomUUID() 遭遇非安全上下文 (Non-secure context) 报错

一、问题概述：Secure Context 限制引发的 undefined 运行时崩溃

随着现代浏览器对 Web 安全隐私的强化，W3C 规定 crypto.randomUUID() 仅在“安全上下文 (Secure Context)”下暴露。当前端应用通过普通的 HTTP 协议部署（例如开发测试环境 http://192.168.1.100 或 HTTP 内网域名）访问时，window.crypto.randomUUID 会被浏览器直接设为 undefined！某些开发者仓促使用 Math.random() 替代，又埋下了随机数碰撞的严重隐患。

二、最小复现：非安全上下文中的报错与错误降级陷阱

下面的代码展示了在 HTTP 网页下直接调用 crypto.randomUUID() 发生的运行时崩溃以及使用 Math.random() 的危险后果：

/* 在 HTTP 网页上直接调用: */
try {
  const id = window.crypto.randomUUID(); // 在非安全上下文抛出 TypeError!
} catch (e) {
  console.error(e); // TypeError: window.crypto.randomUUID is not a function
}

/* 错误降级法: 盲目使用 Math.random() 生成 UUID */
// function badUUID() {
//   return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
//     const r = Math.random() * 16 | 0; // 危险！Math.random() 熵值极低且可被预测！
//   });
// }

三、根因分析：W3C 安全上下文机制与密码学安全 PRNG 约束

1. Secure Context 保护：W3C 规范要求所有接触硬件随机数发生器与高权限密码学功能的 API 必须处于 HTTPS 或 localhost / 127.0.0.1 保护之下。2. Math.random 的致命弱点：Math.random() 使用伪随机算法 (PRNG，如 xorshift128+)，在并发场景或多线程 Worker 中极易产生重复数值，且其状态可被攻击者逆向推算。3. `crypto.getRandomValues` 兼容性：即使在非安全上下文或旧版浏览器中，crypto.getRandomValues(array) 通常依然可用（或在 Node.js 环境中通过 require('crypto') 提供），应作为安全的底层降级源。

四、推荐方案：优雅降级策略与全环境安全 UUID 生成纯函数

1. 优先检测原生 API：首先检查 typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'。2. 安全降级源：若原生 API 不可用，使用 crypto.getRandomValues(new Uint8Array(16)) 或 Node.js crypto.randomBytes(16)。3. 严格遵循 RFC 4122 v4 格式：按位覆盖第 6 字节的 Version (0x40) 与第 8 字节的 Variant (0x80) 比特位。

五、完整代码：跨平台全环境安全 UUID v4 产生器纯函数

下面的 TypeScript 代码示范如何构建一个零依赖、符合密码学安全标准且兼容 HTTP / HTTPS / Node.js 的全环境 UUID v4 生成纯函数。

function safeGenerateUUID(): string {
  // 1. 优先使用原生 API (要求 HTTPS / localhost 安全上下文)
  if (
    typeof crypto !== "undefined" &&
    typeof crypto.randomUUID === "function"
  ) {
    return crypto.randomUUID();
  }

  // 2. 降级方案：使用密码学安全的 getRandomValues (支持大部分非 HTTPS 浏览器)
  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
    const bytes = new Uint8Array(16);
    crypto.getRandomValues(bytes);

    // RFC 4122 v4 位覆盖: Version 4 (0x40) 与 Variant 10xx (0x80)
    bytes[6] = (bytes[6] & 0x0f) | 0x40;
    bytes[8] = (bytes[8] & 0x3f) | 0x80;

    const hex = Array.from(bytes)
      .map((b) => b.toString(16).padStart(2, "0"))
      .join("");

    return [
      hex.substring(0, 8),
      hex.substring(8, 12),
      hex.substring(12, 16),
      hex.substring(16, 20),
      hex.substring(20, 32),
    ].join("-");
  }

  throw new Error("当前运行环境缺少密码学安全的随机数发生器 (Crypto API)");
}

console.log("生成的安全 UUID:", safeGenerateUUID());

六、常见错误方案

在非 HTTPS 环境下直接假设 crypto.randomUUID 存在导致全站报错卡死；使用字符串随机切片或时间戳拼接假装成 UUID 格式；把 Math.random() 用于生成安全 Session ID。

七、边界条件：Node.js SSR 环境、Web Worker 与旧版 WebKit 兼容

在 Nuxt / Next.js 服务端渲染 (SSR) 中，Node.js 16.7.0+ 已原生支持 globalThis.crypto.randomUUID()；而在极旧的环境中需通过 import('node:crypto') 导入；Web Worker 内部可直接访问 self.crypto。

八、如何验证 UUID 生成器安全性

测试在 http:// 局域网 IP 域名下的报错防护能力；验证生成的字符串第 15 位字符永远为 '4'，第 20 位字符为 '8', '9', 'a', 'b' 之一；确保没有任何依赖 Math.random() 的漏洞。

九、FAQ

问：为什么 localhost 访问时 crypto.randomUUID() 不报错？答：W3C 规范将 http://localhost 与 http://127.0.0.1 明确定义为特许安全上下文 (Potentially Trustworthy Origin)，因此开发者本地调试不会受阻。

问：使用第三方库如 uuid 库 (v4) 会遇到这个报错吗？答：标准的 uuid npm 包内部内置了对 crypto.getRandomValues 的安全降级，不会因为缺少 randomUUID 而抛出致命崩溃。

问：可以用微秒时间戳拼接生成唯一 ID 吗？答：高并发微服务场景下仅靠时间戳必然发生碰撞，时间戳只能保证粗略时序，不能代替 128 位物理随机熵。

十、总结

W3C Secure Context 限制是现代 Web 安全的标准屏障。通过判定环境并使用 crypto.getRandomValues 替代 Math.random() 降级，能同时兼顾 HTTP 开发调试便利与生产级随机数安全。