JavaScript 生成 UUID 的常见方案与避坑指南

问题在于 Date.now() 精度仅为毫秒级。在高并发或用户快速点击场景下，同一毫秒内可能生成多个相同 ID。即便增加自增计数器，代码复杂度上升且仍无法解决可预测性问题。此方案仅适合对安全性要求极低的临时场景。

方案三：浏览器指纹混合

试图通过设备信息（屏幕分辨率、UserAgent 等）混合生成哈希值来保证唯一性：

function fingerprintUUID() {
    const screenInfo = `${screen.width}x${screen.height}x${screen.colorDepth}`;
    const userAgent = navigator.userAgent;
    const language = navigator.language;
    const platform = navigator.platform;
    const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
    const seed = `${screenInfo}-${userAgent}-${language}-${platform}-${timezone}-${Date.now()}-${Math.random()}`;
    
    let hash = 0;
    for (let i = 0; i < seed.length; i++) {
        const char = seed.charCodeAt(i);
        hash = ((hash << 5) - hash) + char;
        hash = hash & hash;
    }
    
    const hex = Math.abs(hash).toString(16).padStart(8, '0');
    const randomPart = Math.random().toString(16).substring(2, 10);
    return `${hex.substring(0, 8)}-${hex.substring(0, 4)}-4${hex.substring(1, 4)}-${randomPart.substring(0, 4)}-${randomPart.substring(4, 12)}${Date.now().toString(16).substring(0, 4)}`;
}

这种方法并不靠谱。同型号设备生成的指纹往往一致，且现代浏览器隐私保护策略（如 User-Agent Reduction）正在逐步屏蔽此类信息。这属于过度设计，不建议采用。

方案四：使用 uuid npm 包

生产环境推荐使用成熟的第三方库，如 uuid。它兼容 Node.js、浏览器及 React Native，内部优先调用加密级随机接口：

npm install uuid

import { v4 as uuidv4 } from 'uuid';
const id = uuidv4();
console.log(id);

该库在 Node 环境下使用 crypto 模块，浏览器端优先降级使用 crypto.getRandomValues。经过多年大规模验证，其碰撞概率极低。注意升级大版本时需关注 API 变更，批量生成时性能略逊于原生 API。

方案五：浏览器原生 crypto.randomUUID()

现代浏览器（Chrome 92+、Firefox 95+、Safari 15.4+）支持原生方法，无需依赖外部包：

const id = crypto.randomUUID();
console.log(id);

性能比 uuid 包快约 30%-50%，且能减小打包体积。但兼容性仍是瓶颈，老旧环境会报错。稳妥做法是封装降级逻辑：

function generateUUID() {
    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
        return crypto.randomUUID();
    }
    // 降级方案：使用 crypto.getRandomValues 或 Math.random
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
        const r = (typeof crypto !== 'undefined' && crypto.getRandomValues)
            ? crypto.getRandomValues(new Uint8Array(1))[0] % 16
            : Math.random() * 16 | 0;
        const v = c === 'x' ? r : (r & 0x3 | 0x8);
        return v.toString(16);
    });
}

生产环境常见翻车现场

1. 低端安卓机撞 ID：某活动页因使用 Math.random()，导致部分机型订单 ID 重复，引发重复扣款投诉。解决方案是强制使用 crypto 相关接口并配合服务端兜底。
2. 循环并发冲突：批量导入时，短时间循环生成 ID 未考虑种子更新频率，导致大量重复。应确保每次生成都有足够熵源。
3. Mock 数据污染：测试脚本使用固定种子生成 Mock ID，误连生产环境导致脏数据。规范上严禁在非标准环境中使用非标准 UUID 格式。

实战场景代码示例

1. 草稿箱本地存储

结合 SessionStorage 和 LocalStorage，使用双 ID 策略（草稿 ID + 版本 ID）：

class DraftManager {
    constructor() {
        this.STORAGE_KEY = 'user_drafts';
        this.currentDraftId = sessionStorage.getItem('current_draft_id') || this.createNewDraft();
    }

    createNewDraft() {
        const id = crypto.randomUUID ? crypto.randomUUID() : `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
        sessionStorage.setItem('current_draft_id', id);
        return id;
    }

    saveDraft(content) {
        const drafts = this.getAllDrafts();
        drafts[this.currentDraftId] = {
            content,
            updateTime: Date.now(),
            versionId: crypto.randomUUID ? crypto.randomUUID() : Date.now()
        };
        localStorage.setItem(this.STORAGE_KEY, JSON.stringify(drafts));
    }

    getAllDrafts() {
        try {
            return JSON.parse(localStorage.getItem(this.STORAGE_KEY)) || {};
        } catch {
            return {};
        }
    }
}

2. PWA 离线数据同步

利用 IndexedDB 存储待同步任务，使用 localId 作为离线阶段的唯一凭证：

class OfflineSyncManager {
    constructor() {
        this.DB_NAME = 'offline_data';
        this.STORE_NAME = 'pending_requests';
        this.db = null;
        this.initDB();
    }

    async initDB() {
        return new Promise((resolve, reject) => {
            const request = indexedDB.open(this.DB_NAME, 1);
            request.onerror = () => reject(request.error);
            request.onsuccess = () => {
                this.db = request.result;
                resolve();
            };
            request.onupgradeneeded = (event) => {
                const db = event.target.result;
                db.createObjectStore(this.STORE_NAME, { keyPath: 'localId' });
            };
        });
    }

    async addTask(apiEndpoint, payload) {
        const localId = crypto.randomUUID();
        const task = {
            localId,
            apiEndpoint,
            payload,
            createdAt: Date.now(),
            retryCount: 0,
            status: 'pending'
        };
        const transaction = this.db.transaction([this.STORE_NAME], 'readwrite');
        const store = transaction.objectStore(this.STORE_NAME);
        await store.add(task);
        console.log(`任务已离线保存，本地 ID：${localId}`);
        return localId;
    }
}

3. WebSocket 消息防重发

每条消息携带唯一 ID，服务端返回 ACK 确认，客户端维护 Pending 队列：

class ReliableWebSocket {
    constructor(url) {
        this.url = url;
        this.ws = null;
        this.pendingMessages = new Map();
    }

    connect() {
        this.ws = new WebSocket(this.url);
        this.ws.onopen = () => {
            console.log('连接成功');
        };
        this.ws.onmessage = (event) => {
            const data = JSON.parse(event.data);
            if (data.type === 'ACK') {
                this.pendingMessages.delete(data.messageId);
            }
        };
    }

    send(payload) {
        const messageId = crypto.randomUUID();
        const message = { id: messageId, timestamp: Date.now(), payload };
        if (this.ws.readyState === WebSocket.OPEN) {
            this.doSend(message);
        }
        return messageId;
    }

    doSend(message) {
        this.ws.send(JSON.stringify(message));
        this.pendingMessages.set(message.id, { ...message, sendTime: Date.now() });
        setTimeout(() => this.checkAck(message.id), 3000);
    }

    checkAck(messageId) {
        if (this.pendingMessages.has(messageId)) {
            const msg = this.pendingMessages.get(messageId);
            if (msg.retryCount < 3) {
                msg.retryCount++;
                this.doSend(msg);
            }
        }
    }
}

调试与验证技巧

• 暴力测试：生成 100 万次 UUID 存入 Set，检查是否有重复。注意 Web Worker 避免阻塞主线程。
• 监控埋点：线上环境可通过 WeakSet 记录最近生成的 ID，发现重复立即上报。
• 日志定位：生成时打印详细上下文（时间、URL、堆栈），便于排查异常来源。

总结与建议

UUID 生成看似简单，实则涉及随机性、安全性和兼容性等多个维度。核心建议如下：

1. 拒绝时间戳当主键：高并发下时间戳极易冲突，且用户修改系统时间会导致混乱。
2. 优先使用原生 API：crypto.randomUUID() 性能最好，但务必做好兼容性降级。
3. 不要自定义格式：遵循标准格式便于跨系统对接，避免后续维护成本。
4. 业务层去重：UUID 不能替代业务逻辑的唯一性校验，需结合业务规则二次确认。

最后提醒，测试环境务必覆盖低端机型和网络波动场景，那是前端真正的炼狱场。愿你的项目里再无重复 ID，少加三天班。