生成唯一标识：uuid （详细攻略）

文章目录

• • 一、核心基础
  • • 1. UUID 是什么？
    • 2. UUID 的版本（核心分类）
    • 3. 主流 uuid.js 库选型
  • 二、安装与基础使用
  • • 1. 安装（支持多种包管理）
    • 2. 核心使用方式（分环境）
    • • 场景1：Node.js/模块化项目（ES Module）
      • 场景2：浏览器非模块化环境（CDN）
      • 场景3：CommonJS（旧版 Node.js）
  • 三、高级用法
  • • 1. 自定义 v4 UUID 生成（指定随机数源）
    • 2. v5 UUID 自定义命名空间
    • 3. 生成无横线的 UUID（精简格式）
    • 4. 批量生成 UUID
  • 四、各版本 UUID 适用场景对比
  • 五、实战场景示例
  • • 1. 前端：生成DOM元素唯一ID
    • 2. 前端：生成本地存储唯一键
    • 3. Node.js：生成订单号（结合时间+UUID）
    • 4. 避免 UUID 重复（极端场景处理）
  • 六、常见问题与解决方案
  • • 1. 打包体积过大
    • 2. 浏览器端 `crypto` 未定义
    • 3. UUID 过长，想缩短
    • 4. Node.js 中 `require('uuid')` 报错
  • 七、性能优化
  • 总结

uuid.js 是用于生成 UUID（通用唯一标识符，Universally Unique Identifier） 的 JavaScript 库，解决前端/Node.js 场景下“生成唯一标识”的核心需求（如订单号、用户唯一ID、缓存键、DOM元素唯一标识等）。以下从核心概念、库选型、使用方法、版本差异、实战场景、性能优化等维度，进行全方位讲解。

一、核心基础

1. UUID 是什么？

UUID 是一个 128 位的数字标识符，通常以 36 个字符的字符串形式呈现（如 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed），具有全球唯一性（理论上重复概率可忽略），无需中央服务器即可生成，是前端/后端最常用的唯一标识方案。

2. UUID 的版本（核心分类）

3. 主流 uuid.js 库选型

前端/Node.js 生态中最常用的两个 UUID 库：

注：日常说的“uuid.js”通常指 uuid 库（npm 下载量超 2000 万/周），下文以该库为核心讲解。

二、安装与基础使用

1. 安装（支持多种包管理）

# npm
npm install uuid –save

# yarn
yarn add uuid

# pnpm
pnpm add uuid

# CDN（浏览器直接引入）
<script src="https://cdn.jsdelivr.net/npm/uuid@9.0.1/dist/umd/uuidv4.min.js"></script>

2. 核心使用方式（分环境）

场景1：Node.js/模块化项目（ES Module）

// 按需导入（推荐，减小打包体积）
import { v1, v4, v5, v7 } from 'uuid';

// 生成 v4 随机 UUID（最常用）
const uuidV4 = v4();
console.log(uuidV4); // 输出示例：3b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed

// 生成 v1 时间戳+MAC UUID
const uuidV1 = v1();
console.log(uuidV1); // 输出示例：d9428888-122b-11e1-b85c-61cd3cbb3210

// 生成 v5 命名空间哈希 UUID（固定输入→固定输出）
const NAMESPACE_URL = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'; // 官方预定义命名空间
const uuidV5 = v5('https://example.com', NAMESPACE_URL);
console.log(uuidV5); // 相同输入会生成相同UUID：b429502d-285b-51df-92b3-5c0458293850

// 生成 v7 时间戳+随机数 UUID（现代推荐）
const uuidV7 = v7();
console.log(uuidV7); // 输出示例：018e8b50-7e0b-7000-8000-000000000000

场景2：浏览器非模块化环境（CDN）

<script src="https://cdn.jsdelivr.net/npm/uuid@9.0.1/dist/umd/uuid.min.js"></script>
<script>
// 生成 v4 UUID
const uuidV4 = uuid.v4();
console.log(uuidV4);

// 生成 v7 UUID
const uuidV7 = uuid.v7();
console.log(uuidV7);
</script>

场景3：CommonJS（旧版 Node.js）

const { v4: uuidv4 } = require('uuid');
const uuid = uuidv4();
console.log(uuid);

三、高级用法

1. 自定义 v4 UUID 生成（指定随机数源）

适用于需要自定义随机数生成逻辑的场景（如加密级随机数）：

import { v4 as uuidv4 } from 'uuid';

// 自定义随机数生成器（示例：使用加密安全的随机数）
const randomBytes = () => {
const array = new Uint8Array(16);
window.crypto.getRandomValues(array); // 浏览器加密随机数
return array;
};

// 生成自定义 v4 UUID
const customUuid = uuidv4({ random: randomBytes() });
console.log(customUuid);

2. v5 UUID 自定义命名空间

除了官方预定义的命名空间（URL、DNS、OID、X500），可自定义命名空间：

import { v5 as uuidv5 } from 'uuid';

// 自定义命名空间 UUID（先生成一个v4作为命名空间）
const MY_NAMESPACE = uuidv4();

// 基于自定义命名空间生成v5 UUID
const uuid1 = uuidv5('user123', MY_NAMESPACE);
const uuid2 = uuidv5('user123', MY_NAMESPACE);
console.log(uuid1 === uuid2); // true（相同输入+命名空间=相同UUID）

3. 生成无横线的 UUID（精简格式）

标准 UUID 含 4 个横线，如需精简可手动去除：

import { v4 as uuidv4 } from 'uuid';

// 生成无横线 UUID
const uuidWithOutDash = uuidv4().replace(/–/g, '');
console.log(uuidWithOutDash); // 输出示例：3b9d6bcdbbfd4b2d9b5dab8dfbbd4bed

4. 批量生成 UUID

适用于一次性生成多个唯一标识（如批量创建测试数据）：

import { v4 as uuidv4 } from 'uuid';

// 批量生成10个UUID
const generateBatchUuids = (count) => {
return Array.from({ length: count }, () => uuidv4());
};

const uuidList = generateBatchUuids(10);
console.log(uuidList); // 输出10个不同的UUID数组

四、各版本 UUID 适用场景对比

五、实战场景示例

1. 前端：生成DOM元素唯一ID

<template>
<div :id="elementId">唯一标识的DOM元素</div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { v4 as uuidv4 } from 'uuid';

const elementId = ref('');

onMounted(() => {
// 生成唯一DOM ID
elementId.value = `component-${uuidv4().substring(0, 8)}`; // 精简为8位，避免过长
});
</script>

2. 前端：生成本地存储唯一键

import { v4 as uuidv4 } from 'uuid';

// 存储用户临时数据，用UUID作为键
const saveTempData = (data) => {
const tempKey = `temp_${uuidv4()}`;
localStorage.setItem(tempKey, JSON.stringify(data));
return tempKey; // 返回键，方便后续读取/删除
};

// 使用示例
const key = saveTempData({ name: 'test', age: 20 });
console.log('存储键：', key);

3. Node.js：生成订单号（结合时间+UUID）

const { v4: uuidv4 } = require('uuid');
const dayjs = require('dayjs');

// 生成订单号：时间戳 + UUID后8位（易读且唯一）
const generateOrderNo = () => {
const timestamp = dayjs().format('YYYYMMDDHHmmss'); // 时间戳
const uuidSuffix = uuidv4().substring(–8); // UUID后8位
return `ORDER_${timestamp}_${uuidSuffix}`;
};

// 使用示例
const orderNo = generateOrderNo();
console.log('订单号：', orderNo); // 输出示例：ORDER_20260306153022_4bed8dfb

4. 避免 UUID 重复（极端场景处理）

虽然 UUID 重复概率极低，但高并发场景可增加校验：

import { v4 as uuidv4 } from 'uuid';

// 生成并校验唯一的UUID（防止极端重复）
const generateUniqueUuid = (existingUuids = []) => {
let uuid;
do {
uuid = uuidv4();
} while (existingUuids.includes(uuid)); // 校验是否已存在
return uuid;
};

// 使用示例：已有UUID列表
const existingList = ['3b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'];
const newUuid = generateUniqueUuid(existingList);
console.log('新唯一UUID：', newUuid);

六、常见问题与解决方案

1. 打包体积过大

• ❌ 原因：导入了全版本（v1/v3/v4/v5/v7），未按需导入
• ✅ 解决：仅导入需要的版本（如只需要v4）// 错误（导入全量）
  import uuid from 'uuid';
  // 正确（按需导入，体积减小80%）
  import { v4 as uuidv4 } from 'uuid';

2. 浏览器端 crypto 未定义

• ❌ 原因：部分老旧浏览器不支持 window.crypto（uuid 库依赖其生成随机数）
• ✅ 解决：引入 polyfill 或降级为非加密随机数// 降级方案：自定义随机数生成器（仅用于非加密场景）
  import { v4 as uuidv4 } from 'uuid';

  const fallbackRandom = () => {
  const array = new Uint8Array(16);
  for (let i = 0; i < 16; i++) {
  array[i] = Math.floor(Math.random() * 256); // 普通随机数
  }
  return array;
  };

  const uuid = uuidv4({ random: fallbackRandom() });

3. UUID 过长，想缩短

• ❌ 原因：标准UUID 36位，部分场景（如URL参数）需要更短
• ✅ 解决：使用 short-uuid 库或手动截取（注意：截取会降低唯一性，建议至少保留16位）// 方案1：使用short-uuid
  import shortUuid from 'short-uuid';
  const shortId = shortUuid.generate(); // 输出示例：Xy3579jG9s87G8s7
  // 方案2：手动截取（简易版）
  const uuid = uuidv4().substring(0, 16); // 保留前16位

4. Node.js 中 require('uuid') 报错

• ❌ 原因：uuid 库 v8+ 仅支持 ES Module，旧版 Node.js 未配置
• ✅ 解决：
• 安装兼容版：npm install uuid@7.x –save
• 或在 package.json 中添加 "type": "module" 启用 ES Module

七、性能优化

总结