1.5万Star的UUID生成库：零依赖，npm周下载量过亿

uuid 在 GitHub 上拿到了 1.5 万 Star，npm 的周下载量超过 1 亿次。

它做的事情不复杂：按照 RFC9562 规范生成 UUID。但"不复杂"的背后是覆盖了 7 个 UUID 版本、横跨浏览器、Node.js、React Native 和命令行的全场景支持，外加零依赖。

7 个版本，各有用处

UUID 不只有一种。RFC9562 定义了多个版本，各自有不同的生成策略：

• v1：时间戳加 MAC 地址，能追溯到生成机器的具体时间点
• v3：基于命名空间做 MD5 哈希，同样的输入永远产出同样的 UUID
• v4：纯随机数，使用率最高的版本
• v5：基于命名空间做 SHA-1 哈希，RFC 推荐用 v5 替代 v3
• v6：v1 的字段重排版，把时间戳高位放到前面，对 B-tree 索引更友好
• v7：Unix 毫秒时间戳打头，后面补随机数，天然按时间递增

v8 留给实验场景，库本身不提供生成方法，但 validate() 和 version() 能识别 v8 UUID。

一行命令上手

npm install uuid

import { v4 as uuidv4 } from 'uuid';
uuidv4(); // 'b18794e8-5d0d-417c-b361-ba38e78411b4'

命令行也能直接用：

npx uuid
ddeb27fb-d9a0-4624-be4d-4615062daed4

指定版本生成：

npx uuid v1
npx uuid v7
npx uuid v3 "hello" "1b671a64-40d5-491e-99b0-da01ff1f3341"

不只是生成 UUID

除了生成，uuid 还提供了校验和解析能力：

validate() 判断一个字符串是否为合法 UUID，version() 返回 RFC 版本号：

import { validate, version } from 'uuid';

validate('not a uuid'); // false
validate('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // true
version('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // 4

两个方法组合就能做按版本过滤：

function isV4(uuid) {
  return validate(uuid) && version(uuid) === 4;
}

parse() 把 UUID 字符串转成 16 字节的 Uint8Array，stringify() 反着来。这在把 UUID 写入二进制协议或数据库 binary 字段时会用到。另有两个常量：NIL（全零 UUID）和 MAX（全 F UUID），在边界条件处理和数据库查询中偶尔用得上。

v7 解决了一个实际问题

MySQL InnoDB 用 B+ 树按主键排序存储。如果主键是随机 UUID，每次 INSERT 都可能导致页分裂，写入性能受影响。v7 UUID 把 Unix 毫秒时间戳放在前 48 位，让新生成的 ID 大致递增，减少页分裂，写入性能接近自增 ID。这也是 v7 在 uuid v10 版本中被加入的原因：社区对时间排序 UUID 的需求一直存在。

两个注意点

从 v11 开始，uuid 不再支持 CommonJS，只提供 ESM。还在用 require('uuid') 的项目需要改成 import 语法。

v1、v6、v7 这些时间相关方法在不传 options 时会用内部计数器保证同一毫秒内的唯一性；传了 options 则表示你自行控制参数，内部计数器不参与。这是 v11 修复的一个问题，之前 options 和内部状态可能相互干扰。

React Native / Expo 用户可能遇到 getRandomValues() not supported，在入口文件最前面引入 react-native-get-random-values 即可。

总结

uuid 属于那种"一个库解决一个问题"的类型。API 干净，TypeScript 类型完备，零依赖、支持 tree-shaking。从生成、校验到解析，RFC9562 定义的操作它都提供了对应方法。项目里需要 UUID，不管跑在浏览器还是 Node 端，npm install uuid 就够用了。

king。从生成、校验到解析，RFC9562 定义的操作它都提供了对应方法。项目里需要 UUID，不管跑在浏览器还是 Node 端，npm install uuid 就够用了。