crypto.randomUUID() 报错：不是函数？

Question

在使用 `crypto.randomUUID()` 时，部分开发者遇到“`crypto.randomUUID is not a function`”错误。该问题通常出现在 Node.js 版本低于 14.17.0 或运行环境不支持此 API 的浏览器中。`randomUUID()` 是较新的 Web Crypto API 方法，旧版环境未实现。此外，在某些打包工具（如 Webpack 4）或测试环境（如 Jest 模拟环境）中，`crypto` 模块可能被替换或未完整模拟，也会导致调用失败。解决方案包括升级 Node.js 至 14.17.0+，确保运行环境兼容，并在不支持的环境中降级使用 `uuid` 库或添加 polyfill。

Answer 1

深入解析 crypto.randomUUID() 兼容性问题与解决方案

1. 问题背景：crypto.randomUUID() 是什么？

crypto.randomUUID() 是 Web Crypto API 的一部分，自 Node.js 14.17.0 和现代浏览器（如 Chrome 92+、Firefox 95+）起原生支持。它用于生成符合 RFC 4122 标准的 v4 UUID，无需引入第三方库。

调用方式简单：

const uuid = crypto.randomUUID(); // 示例输出: "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"

然而，许多开发者在实际项目中遭遇如下错误：

TypeError: crypto.randomUUID is not a function

2. 常见触发场景分析

该错误并非代码逻辑问题，而是运行时环境缺失或模拟不完整所致。以下是主要触发场景：

• Node.js 版本低于 14.17.0
• 目标浏览器不支持（如 IE、旧版 Safari）
• Webpack 4 或更早版本打包时对全局对象处理不当
• Jest 测试环境中未正确模拟 crypto 对象
• 使用了某些 polyfill 库但未覆盖 randomUUID 方法
• 运行于非标准 JavaScript 引擎（如 React Native 默认环境）
• TypeScript 编译目标设置为过低的 ES 版本
• Deno 或 Bun 等新兴运行时兼容层尚未完全对齐
• CI/CD 流水线中测试环境 Node 版本陈旧
• 微前端沙箱机制劫持并弱化了全局 crypto 实例

3. 深度排查流程图

graph TD
      A[出现 crypto.randomUUID is not a function] --> B{Node.js 环境?}
      B -->|是| C[检查 Node 版本 >= 14.17.0?]
      B -->|否| D[检查浏览器兼容性]
      C -->|否| E[升级 Node.js 或降级方案]
      C -->|是| F[检查打包工具配置]
      D --> G[查询 caniuse.com 支持情况]
      G --> H[是否需支持旧浏览器?]
      H -->|是| I[引入 polyfill 或 uuid 库]
      F --> J[Webpack 是否替换 crypto?]
      J -->|是| K[配置 alias 或 shim]
      J -->|否| L[检查 Jest setupFilesAfterEnv]
      L --> M[手动模拟 crypto.randomUUID]

4. 解决方案矩阵对比

方案	适用场景	维护成本	性能表现	包体积影响
升级 Node.js 至 16+	服务端应用	低	最优	无
使用 uuid@9+	全平台兼容	中	良好	+5KB
Polyfill + 条件导入	前端构建项目	高	良好	+2KB
Jest 手动 mock	单元测试	低	N/A	无
Webpack ProvidePlugin	老旧构建系统	中	良好	无
条件编译 (Babel)	多端输出	高	良好	可控
nano-id 替代方案	轻量级需求	低	极优	+1KB
自实现 crypto fallback	高度定制化	极高	一般	无
Feature Detection + 动态加载	大型 SPA	中	良好	按需
ESBuild 自动 polyfill 插件	现代化构建链路	低	优秀	智能注入

5. 实战代码示例：安全调用封装

为确保跨环境兼容，推荐封装一个健壮的 UUID 生成器：

function generateUUID() {
    // 检测原生支持
    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
      return crypto.randomUUID();
    }

    // Polyfill for v4 UUID
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
      const r = (Math.random() * 16) | 0;
      const v = c == 'x' ? r : (r & 0x3) | 0x8;
      return v.toString(16);
    });
  }

  // 使用示例
  console.log(generateUUID());

此方法结合了原生优先策略与优雅降级机制，适用于生产环境。

6. 构建工具适配建议（以 Webpack 为例）

在 Webpack 4 中，默认会将 crypto 替换为空对象。可通过以下配置修复：

module.exports = {
  resolve: {
    fallback: {
      crypto: require.resolve('crypto-browserify')
    }
  },
  plugins: [
    new webpack.ProvidePlugin({
      crypto: ['crypto', 'web']
    })
  ]
};

对于 Webpack 5+，建议启用 node: { global: true, crypto: 'empty' } 并显式引入 polyfill。

7. Jest 测试环境模拟实现

在 jest.setup.js 中添加模拟逻辑：

Object.defineProperty(globalThis, 'crypto', {
    value: {
      randomUUID: () => 'test-uuid-' + Math.random().toString(36).substr(2, 9)
    },
    writable: true
  });

并在 package.json 中引用：

"jest": {
    "setupFilesAfterEnv": ["<rootDir>/jest.setup.js"]
  }