puter.randName() 随机名称生成完全指南：在 Puter.js 中创建域名安全的唯一标识

2026-09-08 19:54:12作者：伍霜盼Ellen

puter.randName() 是 Puter.js（本项目开源的“Internet Computer”前端 JavaScript SDK）提供的一个实用工具函数，用于生成由**随机形容词 + 随机名词 + 随机数字（0–9999）**组合而成的、对域名安全的随机名称。无论是为临时文件、目录、KV 键、应用名还是托管子域名生成唯一标识，它都是官方测试与示例中最常用的命名工具。阅读本文后，你将掌握它的语法、底层词库实现、可预期的字符特征与碰撞概率，并能结合源码与测试理解其适用边界。

什么是 `puter.randName()`

在 Puter.js 文档的 Utilities 索引中，puter.randName() 与 puter.print()、puter.appID、puter.env 一同被列为官方基础工具。官方为它给出的能力定义是：generate a random domain-safe name（生成一个域名安全的随机名称）。

从字面上可以拆解为两层含义：

随机（random）：每次调用都会组合不同的形容词、名词与数字，输出几乎不重复的名称。
域名安全（domain-safe）：产物只包含小写字母、数字与连字符，可用于文件名、键名乃至子域名等对字符集敏感的场景。

官方在其文档元信息中声明，该函数支持以下运行平台：websites（网页）、apps（应用）、nodejs（Node.js）、workers（Puter 云端 Worker），即无论是纯浏览器页面还是 Node.js 后端环境，都能以相同方式调用。

语法与参数

puter.randName() 的完整语法如下：

puter.randName()
puter.randName(separator)

参数 `separator`（String）

用于分隔名称三个组成部分的分隔符。默认值为 -（连字符），可以不传；传入其他字符串（例如 _）即可替换全部分隔位置。

返回值

一个字符串。按默认分隔符输出时，结构形如：

clever-idea-123

即 形容词 + 分隔符 + 名词 + 分隔符 + 0～9999 的随机整数。官方文档给出的示例为 clever-idea-123。

基础使用示例

官方文档提供了一个可直接运行的 HTML 页面示例，把随机名称输出到页面（puter.print 的具体说明见 print 文档）：

<html>
  <body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
      puter.print(puter.randName());
    </script>
  </body>
</html>

在支持 puter 全局对象的浏览器或 App 环境中，也可以直接调用：

// 使用默认分隔符 "-"
console.log(puter.randName());
// 可能输出: eager-ocean-4821

// 使用自定义分隔符 "_"
console.log(puter.randName('_'));
// 可能输出: gentle_panda_77

// 使用自定义分隔符 "."（适合拼接成伪域名片段）
console.log(puter.randName('.'));

从源码看底层实现原理

puter.randName 的实现并不神秘，在 Puter.js 主入口源码中即可读到完整逻辑：

randName = function (separateWith = '-') {
    const first_adj = [ 'helpful', 'sensible', 'loyal', /* ... */ ];
    const nouns = [ 'street', 'roof', 'floor', /* ... */ ];
    // return a random combination of first_adj + noun + number (between 0 and 9999)
    // e.g. clever-idea-123
    return (
        first_adj[Math.floor(Math.random() * first_adj.length)] +
        separateWith +
        nouns[Math.floor(Math.random() * nouns.length)] +
        separateWith +
        Math.floor(Math.random() * 10000)
    );
};

词库规模

通过对源码逐条统计（见上链接中 first_adj 与 nouns 两个数组），可以精确量化它的随机空间：

组成部分	数据规模	样本
形容词（first_adj）	39 个	helpful、clever、bright、gentle、brave、bold……
名词（nouns）	93 个	street、idea、dog、ocean、panda、harp……
数字	0～9999 共 10000 个	随机取整

三者组合理论上可产生 39 × 93 × 10000 ≈ 3627 万（约 3627 万）种不同名称组合。需要说明：这属于“高熵随机名”而非 UUID，它不保证全局绝对唯一，但足以满足绝大多数临时命名需求。

字符特征为何“域名安全”

名称的三个部分全部来自小写英文词库，数字部分为十进制整数，分隔符由你指定。因此在不传参或使用 - 时，输出严格符合字符类：

^[a-z0-9-]+$

即仅包含小写字母、数字与连字符，不含空格、下划线之外的符号或大写字母。这使它可以直接用作文件名、目录名、URL path 片段、KV 键乃至子域名的组成部分，而不必担心转义或 URL 编码问题。

测试用例如何验证行为

官方 API 测试套件（util.suite.ts）为该函数固化了三条关键契约，恰好覆盖上文所述的行为特征：

返回非空字符串，且字符域受限——断言输出必须匹配 /^[a-z0-9-]+$/（小写字母、数字、连字符），从测试层面锁定了“域名安全”的定义；
每次调用产出新名称——连续两次调用结果必须不同；
支持自定义分隔符——传入 '_' 时输出必须包含 _ 且不包含 -。

由此可以看出，官方在测试中把“纯客户端工具、所有平台行为一致”作为 puter.randName 的基本定位。

实际工程中的应用模式

在仓库中，puter.randName() 并非孤立 API，而是贯穿 SDK 测试与文档的高频命名设施：

文件与目录的临时命名

在 FS 测试用例中，几乎所有 puter.fs.write、puter.fs.mkdir、puter.fs.stat、puter.fs.rename、puter.fs.copy、puter.fs.delete 操作都先用 puter.randName() 生成唯一的临时文件/目录名，例如：

let randName = puter.randName();
const result = await puter.fs.write(randName, 'testValue');
// 之后用同一名称 read / stat / delete

这正是你在业务代码中管理临时资源的标准做法：用 randName() 生成名称，用完即删，天然避免与其他用户/进程的命名冲突。FS API 的更多参数见 FS 概览文档与具体方法文档（如 write、read）。

KV 存储的键名

在 KV 测试用例中，键名同样大量拼接 puter.randName() 以保证唯一性，例如 'batchArr-' + puter.randName() + '-'。对 KV 这类“键即地址”的存储而言，随机键是避免数据互相覆盖的简单可靠手段。

子域名与命名类 API

puter.randName() 的命名能力与 Apps、Hosting（站点托管）、Workers、KV 等子系统天然契合：官方在 Apps、Hosting、Events、KV、Workers 系列文档中都用它来演示如何为应用、站点、Worker、事件处理器生成不冲突的名称。例如：

// 生成一个站点/应用默认名
const defaultName = puter.randName();
// 生成带语义前缀的 KV 键
const key = `session-${puter.randName()}`;

从仓库结构看，官方 CLI 的 worker、site 相关命令也依赖同一命名逻辑，可以推断 puter.randName() 是 Puter 生态内生成默认名称的统一工具。

使用建议与边界

综合文档、源码与测试，使用时有几点值得注意：

适用场景：临时文件/目录名、KV 随机键、默认应用名/子域名占位、测试隔离命名。生成结果自带记忆点（如 eager-ocean-4821），比纯 UUID 更容易在日志中被人眼辨识。
不要用于安全令牌：虽然组合空间约 3627 万，但它基于 Math.random() 且不含密码学熵，不能作为 access token、签名 nonce 等安全凭据；这类场景应使用专用的安全随机工具。
不保证绝对唯一：名称只是“大概率唯一”。若写入文件系统时希望彻底避免覆盖，可以结合 FS 写入选项（如 overwrite: false、dedupeName: true，参考 FS 测试中的用法）做去重兜底。
自定义分隔符的取舍：传入 _ 或 . 后输出将不再严格属于 [a-z0-9-] 字符类，需自行评估下游是否接受；默认的 - 最稳妥。