UUID版本详解

每个UUID版本——v1到v8——包含结构图、用例、碰撞风险和JavaScript代码示例。

UUID结构

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

time_low (32 bits)time_mid (16 bits)M = version (4 bits) + time_hi (12)N = variant (2 bits) + clock (14)node / random (48 bits)

UUID v1Time-based (MAC)Sortable

结构

timestamp (60-bit) + clock seq (14-bit) + MAC (48-bit)

碰撞风险

Very low

6ba7b810-9dad-11d1-80b4-00c04fd430c8

优点

+Globally unique
+Sortable by time
+Embeds creation time

缺点

−Exposes MAC address (privacy risk)
−Requires MAC or pseudo-random node
−Clock adjustments can cause duplicates

最佳用途

Legacy systems. Avoid in new projects due to MAC address exposure.

UUID v3Name-based (MD5)Not sortable

结构

MD5(namespace UUID + name) → UUID

碰撞风险

MD5 collision risk (low for UUIDs)

6fa459ea-ee8a-3ca4-894e-db77e160355e

优点

+Deterministic — same input = same UUID
+Can recreate UUIDs from known inputs

缺点

−MD5 is cryptographically weak
−Not random — attackers can predict given namespace+name
−Prefer v5 for new projects

最佳用途

Generating UUIDs from URLs, email addresses, or other stable identifiers. Use v5 instead.

UUID v4RandomNot sortable

结构

122 random bits + 4-bit version + 2-bit variant

碰撞风险

Negligible (2^122 possibilities)

550e8400-e29b-41d4-a716-446655440000

优点

+Extremely low collision probability
+No timestamp/MAC leakage
+Simple generation — no state needed
+Most widely supported

缺点

−Not sortable by generation time
−Random order degrades B-tree performance in databases
−Cannot verify when a UUID was created

最佳用途

Default choice for most applications. IDs for records, sessions, tokens.

UUID v5Name-based (SHA-1)Not sortable

结构

SHA-1(namespace UUID + name) → UUID (top 128 bits)

碰撞风险

SHA-1 — extremely low for UUID purposes

886313e1-3b8a-5372-9b90-0c9aee199e5d

优点

+Deterministic like v3, but uses SHA-1
+Stronger hash than MD5 (v3)
+Standard namespaces: DNS, URL, OID, X.500

缺点

−SHA-1 is fully deterministic — not suitable for secrets
−Truncates SHA-1 to 128 bits

最佳用途

Deterministic IDs from a namespace + name. Example: UUID for 'https://example.com' is always the same.

UUID v7Time-ordered RandomSortable

结构

Unix ms timestamp (48-bit) + version (4-bit) + random (74-bit)

碰撞风险

Very low (74 random bits)

018f0b2d-4c9e-7abc-89de-f012345678ab

优点

+Sortable by time (great for database primary keys)
+Does NOT expose MAC address
+Near-zero collision probability
+RFC 9562 standard

缺点

−Slightly less entropy than v4 (74 vs 122 bits)
−Requires a time source
−Newer — less library support than v4

最佳用途

Database primary keys where sort order matters. Replaces v1 for time-ordered UUIDs.

UUID v8CustomSortable

结构

128 bits, content defined by the implementation

碰撞风险

Depends on implementation

2489e9ad-f195-8b67-72da-3291d8c9fc1b

优点

+Fully customizable
+Useful for embedding application-specific data

缺点

−No standard semantics — interoperability must be documented
−Not widely supported

最佳用途

Experimental or vendor-specific use cases where v1–v7 don't fit.

快速比较

Version	Method	Sortable	Privacy-safe	Deterministic
v1	Time + MAC	✅	❌ (MAC leak)	❌
v3	MD5 hash	❌	✅	✅
v4	Random	❌	✅	❌
v5	SHA-1 hash	❌	✅	✅
v7	Time + Random	✅	✅	❌
v8	Custom	—	—	—

在代码中生成UUID

// JavaScript / Node.js (built-in, Node 15+)
import { randomUUID } from 'crypto';
const v4 = randomUUID();  // → "550e8400-e29b-41d4-a716-446655440000"

// Browser
const v4 = crypto.randomUUID();

// UUID v7 (npm: uuid package v10+)
import { v7 as uuidv7 } from 'uuid';
const v7 = uuidv7();  // → "018f0b2d-4c9e-7abc-89de-f012345678ab"

// Python
import uuid
v4 = str(uuid.uuid4())  # Random
v5 = str(uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com'))

# PostgreSQL
SELECT gen_random_uuid();        -- v4 (pg 13+)
SELECT uuid_generate_v4();       -- v4 (uuid-ossp extension)
SELECT gen_random_uuid()::text;  -- as text

UUID版本常见问题

什么是UUID？

UUID（通用唯一标识符）是RFC 4122中标准化的128位标识符。格式为8-4-4-4-12十六进制字符，由连字符分隔。它们被设计为在没有中央机构的情况下在时间和空间上都是唯一的。

我应该使用哪个UUID版本？

大多数一般用途使用v4——它是随机生成的，碰撞概率极低。如果您需要时间有序的UUID作为数据库主键，请使用v7。如果需要从命名空间+名称对生成确定性UUID，请使用v5。在新项目中避免使用v1，因为它会暴露MAC地址。

UUID v4和v7有什么区别？

UUID v4是纯随机的（122个随机位）。UUID v7在前48位中编码Unix时间戳，后面跟随机位。这使v7 UUID可以按创建时间排序，显著提高了数据库中B-tree索引的性能。

UUID v4 ID真的是唯一的吗？

实际上是的。UUID v4有122个随机位，给出2^122≈5.3×10^36个可能的值。要有50%的碰撞概率，您需要生成约2.7×10^18个UUID——远超任何实际应用。

Version

Method

Sortable

Privacy-safe

Deterministic

Time + MAC

✅

❌ (MAC leak)

❌

MD5 hash

❌

✅

Random

❌

✅

❌

SHA-1 hash

❌

✅

Time + Random

✅

❌

Custom

—

在代码中生成UUID

// JavaScript / Node.js (built-in, Node 15+)
import { randomUUID } from 'crypto';
const v4 = randomUUID();  // → "550e8400-e29b-41d4-a716-446655440000"

// Browser
const v4 = crypto.randomUUID();

// UUID v7 (npm: uuid package v10+)
import { v7 as uuidv7 } from 'uuid';
const v7 = uuidv7();  // → "018f0b2d-4c9e-7abc-89de-f012345678ab"

// Python
import uuid
v4 = str(uuid.uuid4())  # Random
v5 = str(uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com'))

# PostgreSQL
SELECT gen_random_uuid();        -- v4 (pg 13+)
SELECT uuid_generate_v4();       -- v4 (uuid-ossp extension)
SELECT gen_random_uuid()::text;  -- as text

UUID版本常见问题

什么是UUID？

我应该使用哪个UUID版本？

UUID v4和v7有什么区别？

UUID v4 ID真的是唯一的吗？

实际上是的。UUID v4有122个随机位，给出2^122≈5.3×10^36个可能的值。要有50%的碰撞概率，您需要生成约2.7×10^18个UUID——远超任何实际应用。

UUID版本 详解

UUID结构

快速比较

在代码中生成UUID

UUID版本常见问题

References & cheat sheets

UUID版本 详解

UUID结构

快速比较

在代码中生成UUID

UUID版本常见问题

UUID版本详解

UUID版本详解