参考
nanoid 5 的导出入口、API、CLI、字母表与碰撞概率速查。标注 ⚠️ 处为 3.x → 5.x 变化点。导入统一假定
import { ... } from "nanoid"。
一、导出入口（exports）
| 入口 | 导出 | 说明 |
|---|---|---|
nanoid | nanoid、customAlphabet、customRandom、urlAlphabet、random | 主入口，加密随机源 |
nanoid/non-secure | nanoid、customAlphabet | 非加密版（Math.random()），更快 |
nanoid/package.json | — | 包元数据 |
⚠️ 3.x 曾有
nanoid/async、nanoid/url-alphabet子入口，5.x 已移除。urlAlphabet现从主入口具名导出（import { urlAlphabet } from 'nanoid'）。
二、核心 API
| API | 签名 | 作用 |
|---|---|---|
nanoid(size?) | (size = 21) => string | 生成 ID，默认 21 字符、64 字母表 |
customAlphabet(alphabet, size?) | (alphabet, defaultSize = 21) => (size?) => string | 返回「自定义字母表」生成函数 |
customRandom(alphabet, size, getRandom) | (alphabet, defaultSize, getRandom) => (size?) => string | 返回「自定义随机源」生成函数 |
urlAlphabet | string | 默认 URL 安全字母表（64 符）字符串 |
random(bytes) | (bytes) => Uint8Array | 从内部缓冲池取随机字节（底层用） |
ts
import { nanoid, customAlphabet, customRandom, urlAlphabet } from "nanoid";
nanoid(); // 21 字符
nanoid(12); // 12 字符
const a = customAlphabet("ABCDEF123456", 8); // 自定义字母表 + 长度
const b = customRandom(urlAlphabet, 10, (size) =>
new Uint8Array(size).map(() => 256 * Math.random())
); // 自定义随机源（此处仅示意）三、默认字母表与限制
| 项 | 值 |
|---|---|
| 默认长度 | 21 字符 |
| 默认字母表 | A-Za-z0-9_-，共 64 个 URL 安全字符 |
customAlphabet 字母表上限 | 256 个符号（随机字节 0-255） |
| 大小写 | 敏感（A 与 a 不同），存库/比较需大小写敏感 collation |
| 时间有序 | 否（纯随机，不含时间戳） |
四、随机源
| 环境 | 随机源 |
|---|---|
| Node.js | node:crypto 的 webcrypto.getRandomValues（带缓冲池，POOL ×128） |
| 浏览器 | Web Crypto API crypto.getRandomValues（conditional exports 的 browser 条件） |
| React Native | 同浏览器版，需先装并 import react-native-get-random-values polyfill |
nanoid/non-secure | Math.random()（不安全，更快） |
五、CLI（npx nanoid）
| 命令 | 作用 |
|---|---|
npx nanoid | 生成一个默认 ID |
npx nanoid --size 10 | 指定长度 |
npx nanoid --alphabet abc --size 15 | 指定字母表与长度 |
六、与 UUID 对比
| 维度 | nanoid（默认） | UUID v4 | UUID v7 / ULID |
|---|---|---|---|
| 代码体积 | 118 字节（min+brotli） | 423 字节 | 视实现 |
| 字符长度 | 21 | 36（含连字符） | 36 / 26 |
| 随机位 | ~126 位 | ~122 位 | 含时间戳 |
| 字母表 | 64（URL 安全） | 16（hex）+ - | 视实现 |
| 时间有序 | 否 | 否 | 是 |
| 适用 | 短链、资源 ID、前端 key | 通用唯一 ID | 时间有序主键 |
「十亿分之一的重复概率，需生成约 103 万亿个 UUID v4」——nanoid 默认值碰撞概率与之相当。
七、版本与模块系统
| 项 | nanoid 5.x | nanoid 3.x |
|---|---|---|
| 最新版本 | 5.1.x | 3.3.x（维护中） |
| 模块系统 | 纯 ESM（无 require） | ESM + CJS 双产物（可 require） |
engines.node | ^18 || >=20 | 更宽（含 ^10/^12…） |
| 子入口 | .、./non-secure | 还有 ./async、./url-alphabet |
| 适用 | ESM 项目 | CommonJS 项目 |
八、生态工具
| 工具 | 作用 |
|---|---|
| nano-id-cc | 在线碰撞概率计算器（输入字母表/长度/速率） |
| nanoid-dictionary | 常用字母表预设（numbers / lowercase / nolookalikes 等） |
| nanoid-good | 确保 ID 不含不雅词汇 |
react-native-get-random-values | RN 环境的 Web Crypto polyfill |
命令查完，进 指南 · 基础 理解设计，或 指南 · 进阶 看 customAlphabet / customRandom / 选型实战。