---
URL: "/zh-CN/blog/2026-07/VUE-UUID.html"
LLMS_URL: "/zh-CN/blog/2026-07/VUE-UUID.md"
lastUpdated: true
commentabled: true
recommended: true
title: "Vue 集成 UUID 生成唯一标识实践指南"
description: "Vue 集成 UUID 生成唯一标识实践指南"
date:

pageClass: "blog-page-class"
cover: "/covers/vue.svg"
---

## 核心基础

### UUID 是什么

UUID（通用唯一标识符，Universally Unique Identifier） 是一个 128 位用于标识信息的唯一标识符，通常以 32 个十六进制的字符串形式呈现，具有*全球唯一性*（理论上重复概率可忽略），非常适合用于标识网络中的资源、数据记录或其他任何需要唯一标识的实体。

UUID 生成器：[devtool.tech/uuid](https://devtool.tech/uuid)

### uuid.js 库概述

uuid.js 是用于生成 UUID 的 JavaScript 库，解决前端场景下“生成唯一标识”的核心需求，类如订单号、用户唯一ID、缓存键、DOM元素唯一标识等。

### UUID 版本概述

作为 JavaScript 生态系统中最成熟、最广泛使用的 UUID 生成解决方案，uuid.js 提供了多个版本，每个版本都有其独特的生成规则。以下是主要的 UUID 版本及其生成规则：

| 版本 | 生成方法                               | 排序性   | 唯一性保证    | 适用场景             |
| :--- | :------------------------------------- | :------- | :------------ | :------------------- |
| v1   | 基于当前时间戳、计算机MAC地址生成      | 时间排序 | 时间+空间唯一 | 传统系统、日志记录   |
| v2   | DCE安全标识                            | 有限排序 | 安全上下文    | 安全敏感系统         |
| v3   | 基于“命名空间UUID + 字符串”的MD5生成   | 无排序   | 命名空间唯一  | 向后兼容             |
| v4   | 基于加密安全的随机数生成               | 无排序   | 随机性唯一    | 通用场景、快速生成   |
| v5   | 基于“命名空间UUID + 字符串”的SHA-1生成 | 无排序   | 命名空间唯一  | 现代命名需求         |
| v6   | 时间戳重排序                           | 时间排序 | 时间+随机唯一 | 数据库索引优化       |
| v7   | Unix时间戳+随机                        | 时间排序 | 时间+随机唯一 | 现代应用、分布式系统 |

在 Vue.js 中使用 UUID 时，根据实际需求选择合适的版本，各版本 UUID 适用场景对比，如下表所示：

| 版本 | 优点                           | 缺点                              | 典型使用场景                                             |
| :--- | :----------------------------- | :-------------------------------- | :------------------------------------------------------- |
| v1   | 可追溯生成时间/设备、支持排序  | 暴露MAC地址（隐私风险）、易被预测 | 内网设备标识、需按时间排序的日志ID                       |
| v4   | 高随机、隐私性好、生成简单     | 无时间属性、不可排序              | 订单号、用户ID、缓存键、DOM唯一标识（90%场景用这个）     |
| v5   | 固定输入→固定输出、安全性高    | 生成依赖命名空间+输入、无随机属性 | 基于用户手机号/邮箱生成固定唯一ID、资源唯一标识          |
| v7   | 兼顾时间排序和随机性、时间有序 | 部分库版本需手动适配              | 分布式系统ID、日志ID、需要排序的唯一标识（推荐新项目用） |

各版本UUID的性能特征存在显著差异，如下表所示：

| 版本  | 生成速度 | 状态管理 | 排序性能 | 存储效率 |
| :---- | :------- | :------- | :------- | :------- |
| v4    | 最快     | 无状态   | 无顺序   | 16字节   |
| v7    | 快速     | 有状态   | 时间顺序 | 16字节   |
| v1/v6 | 中等     | 有状态   | 时间顺序 | 16字节   |
| v3/v5 | 较慢     | 无状态   | 无顺序   | 16字节   |

## 快速上手

### 安装与引入

首先，我们需要安装 uuid 库，这可以通过 npm 来完成。打开命令行，运行以下命令进行安装：

```bash
npm install uuid
```

安装完成后，可以在需要使用 UUID 的组件或文件中，引入 uuid 库：

```javascript
// 按需导入 v1 版本(基于时间)
import { v1 } from 'uuid'

// 按需导入 v4 版本（基于随机数）
import { v4 } from 'uuid'

// 按需导入 v5 版本(基于 SHA-1 哈希)
import { v5 } from 'uuid'

// 按需导入 v7 版本(较新的时间有序)
import { v7 } from 'uuid'
```

> ⚠️ 重要提示： 为了优化打包体积，请务必按需导入所需要的版本，避免导入全量包导致体积过大。

### 基本用法

安装完成后，可以在代码中引入并使用 uuid 库生成 UUID。以下是一个完整的示例：

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

// 版本1 - 基于时间戳
const uuidV1 = v1()
console.log('v1:', uuidV1)

// 版本3 - 基于命名空间和 MD5
const uuidV3 = v3('example', v5.DNS)
console.log('v3:', uuidV3)

// 版本4 - 随机生成（最常用）
const uuidV4 = v4()
console.log('v4:', uuidV4)

// 版本5 - 基于命名空间和 SHA-1
const NAMESPACE_URL = '6ba7b810-9dad-11d1-80b4-00c04fd430c8' // 官方预定义命名空间
// const sha1UUID = v5('example', v5.DNS);
const uuidV5 = v5('https://example.com', NAMESPACE_URL)
console.log('v5:', uuidV5) // 相同输入会生成相同UUID

// 版本6 - 时间戳重排序
const uuidV6 = v6()
console.log('v6:', uuidV6)

// 版本7 - 基于 Unix 时间戳（现代推荐）
const uuidV7 = v7()
console.log('v7:', uuidV7)
```

## 快速入门示例

### v1 - 基于时间的UUID

v1 UUID 基于时间戳和MAC地址生成，其结构包含60位的时间戳、14位的时钟序列和48位的节点标识。

以下是一个完整的示例，演示如何在页面加载时生成 UUID，并通过按钮点击生成新的 UUID：

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  // 按需导入，减小打包体积
  import { v1 as uuidV1 } from 'uuid'

  // 使用 ref 使其具备响应式能力
  const currentUuid = ref(uuidV1())

  // 生成新 UUID 的方法
  const generateNewUuid = () => {
    currentUuid.value = uuidV1()
  }
</script>

<template>
  <div>
    <p>当前生成的 UUID: {{ currentUuid }}</p>
    <button @click="generateNewUuid">生成新的 UUID</button>
  </div>
</template>
```

### v4 - 基于随机UUID

v4 UUID完全基于随机数生成，是最常用和最简单的UUID版本。

以下是一个完整的示例，演示如何在页面加载时生成 UUID，并通过按钮点击生成新的 UUID：

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  // 按需导入，减小打包体积
  import { v4 as uuidV4 } from 'uuid'

  const currentUuid = ref(uuidV4())

  const generateNewUuid = () => {
    currentUuid.value = uuidV4()
  }
</script>

<template>
  <div>
    <p>当前生成的 UUID: {{ currentUuid }}</p>
    <button @click="generateNewUuid">生成新的 UUID</button>
  </div>
</template>
```

### v5 - 基于命名空间的UUID

v3和v5都基于命名空间和名称的哈希生成，区别在于使用的哈希算法：v3使用MD5，v5使用SHA-1。

| 特性     | v3 (MD5)           | v5 (SHA-1)           |
| :------- | :----------------- | :------------------- |
| 哈希算法 | MD5 (128位)        | SHA-1 (160位)        |
| 安全性   | 较低，存在碰撞风险 | 较高，更安全         |
| 性能     | 较快               | 稍慢但更安全         |
| 推荐使用 | 不推荐，仅向后兼容 | 推荐用于命名空间UUID |

以下是一个完整的示例，演示如何在页面加载时生成 UUID：

```vue
<script setup lang="ts">
  // 按需导入，减小打包体积
  import { v3 as uuidV3, v5 as uuidV5 } from 'uuid'

  // 使用预定义命名空间
  const uuid3 = uuidV3('hello', uuidV3.DNS)
  const uuid5 = uuidV5('hello', uuidV5.DNS)
  // 自定义命名空间
  const customNamespace = '1b671a64-40d5-491e-99b0-da01ff1f3341'
  const customUuid5 = uuidV5('example', customNamespace)
</script>

<template>
  <div>
    <p>当前生成的 uuidV3: {{ uuid3 }}</p>
    <p>当前生成的 uuidV5: {{ uuid5 }}</p>
    <p>自定义的 uuidV5: {{ customUuid5 }}</p>
  </div>
</template>
```

### v7 - 基于Unix时间戳UUID

v7 是基于Unix时间戳的现代UUID版本，专为现代应用设计。

以下是一个完整的示例，演示如何在页面加载时生成 UUID，并通过按钮点击生成新的 UUID：

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  // 按需导入，减小打包体积
  import { v7 as uuidV7 } from 'uuid'

  const currentUuid = ref(uuidV7())

  const generateNewUuid = () => {
    currentUuid.value = uuidV7()
  }
</script>

<template>
  <div>
    <p>当前生成的 UUID: {{ currentUuid }}</p>
    <button @click="generateNewUuid">生成新的 UUID</button>
  </div>
</template>
```

UUIDv7 是一种基于时间戳的有序 UUID，其核心特性是时间可排序性（新生成的 ID 大于旧的 ID），非常适合作为数据库主键或用于需要按时间排序的场景。

## 高级用法 🛠️

### 特殊UUID的使用场景

在 UUID 的世界中，除了我们常见的各种版本的 UUID 外，还存在两个特殊的 UUID 常量，如下表所示：

| UUID 常量 | 简要说明                                                               |
| :-------- | :--------------------------------------------------------------------- |
| uuid.NIL  | 全零的特殊标识符，一个由32个零组成的特殊UUID，是UUID空间中的最小可能值 |
| uuid.MAX  | 全一的特殊标识符，由32个f字符组成，代表了UUID空间中的最大可能值        |

```javascript
import { NIL, MAX } from 'uuid'

// 特殊 UUID 值
console.log('空 UUID:', NIL) // ⇨ '00000000-0000-0000-0000-000000000000'
console.log('最大 UUID:', MAX) // ⇨ 'ffffffff-ffff-ffff-ffff-ffffffffffff'
```

### 验证和版本检测

在现代应用开发中，UUID 的验证和版本检测是确保数据完整性和正确处理的关键环节。uuid.js 库提供了两个强大的工具函数，如下表所示，对于数据验证、路由分发、版本兼容性检查等场景至关重要。

| 函数              | 简要说明                                   |
| :---------------- | :----------------------------------------- |
| `uuid.validate()` | 采用严格的正则表达式以验证是否为有效的UUID |
| `uuid.version()`  | 用于提取UUID的版本信息                     |

```javascript
import { NIL, MAX, validate, version } from 'uuid'

// 验证特殊UUID
console.log('NIL Validation:', validate(NIL)) // true
console.log('MAX Validation:', validate(MAX)) // true

// 检测版本号
console.log('NIL Version:', version(NIL)) // 0
console.log('MAX Version:', version(MAX)) // 15

// 自定义验证逻辑
const isSpecialUUID = (uuid) => {
  if (!validate(uuid)) {
    return false
  }

  const ver = version(uuid)
  return ver === 0 || ver === 15
}

// 处理特殊UUID的实用函数
const handleSpecialUUID = (uuid, defaultValue) => {
  if (uuid === NIL) {
    return defaultValue
  }
  if (uuid === MAX) {
    throw new Error('MAX UUID cannot be used as a normal identifier')
  }
  return uuid
}
```

### 二进制转换功能

在现代应用开发中，UUID 的二进制表示与字符串表示之间的高效转换是至关重要的功能。uuid.js 库提供了下表两个两个强大的API，专门用于处理UUID的二进制格式转换，为开发者提供了灵活的数据处理能力。

| 函数               | 简要说明                                               |
| :----------------- | :----------------------------------------------------- |
| `uuid.parse()`     | 将标准的UUID字符串转换为16字节的数组                   |
| `uuid.stringify()` | 执行反向操作，将16字节的数组转换回标准的UUID字符串格式 |

```javascript
import { parse, stringify } from 'uuid'

const uuidBytes = parse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b')
console.log('parse()函数', uuidBytes)

const uuidString = stringify(uuidBytes)
console.log('stringify()函数', uuidString)
```

uuid.js 的 `parse` 和 `stringify` 函数提供了 UUID 二进制与字符串表示之间高效、可靠的转换能力，这两个 API 在现代应用开发中发挥着重要作用，特别是在需要处理大量 UUID 或对性能有严格要求的场景中。掌握这些二进制转换技巧，可以构建更高效、更节省资源的应用程序，同时保持代码的清晰性和可维护性。

## 实际应用场景分析

在实际开发中，生成 UUID 的场景多种多样，不同的应用场景可能对 UUID 的生成方式有不同的需求。以下是一些常见的应用场景分析，以及如何根据这些场景选择合适的 UUID 生成技巧。

### 数据库记录的唯一标识

在数据库中，每个记录都需要有一个唯一标识符。在这种情况下，使用UUID可以避免手动管理ID的复杂性。对于数据库记录的唯一标识，通常推荐使用版本4的UUID，因为它不依赖于时间戳或机器信息，减少了ID生成时的冲突可能性。

```javascript
import { v4 as uuidV4 } from 'uuid'

const dbRecordUUID = uuidV4()
console.log('为数据库记录生成的UUID:', dbRecordUUID)
```

上面的代码中，我们引入了 uuid 库中的 v4 函数，调用 `v4()` 函数会返回一个符合UUID规范的字符串。

### 分布式系统中的会话跟踪

在微服务、分库分表或离线数据同步场景中，多个节点同时生成 ID 而永不冲突是巨大的优势。UUID 可以用来唯一标识用户的会话，确保用户的状态可以在不同的服务器之间共享。在这种情况下，生成 UUID 的方法需要能够在不同的服务器上产生相同的输出，以便于识别和同步会话。

```javascript
import { v4 as uuidV4 } from 'uuid'

const sessionUUID = v4()
console.log('为分布式系统中的会话生成UUID:', sessionUUID)
```

### 生成无横线的 UUID

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

```javascript
import { v4 as uuidv4 } from 'uuid'

const uuidWithOutDash = uuidv4().replace(/-/g, '')
console.log(uuidWithOutDash)
```

### 批量生成 UUID

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

```javascript
import { v4 as uuidv4 } from 'uuid'

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

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

## 总结

UUID 作为唯一标识符在软件开发中扮演着重要角色，特别是在需要确保数据一致性和唯一性的场景中。uuid.js 通过其完整的功能集、卓越的性能、强大的安全性和优秀的开发者体验，确立了其在 JavaScript UUID 生成领域的领导地位。通过深入了解各版本 UUID 的特性和适用场景，开发者可以做出更明智的技术选择。