Chance.js 在 Node.js 中的安装、引入与实例化完整指南

导读

本文以仓库文档 docs/usage/node.md 为核心，系统讲解 Chance 随机生成器（Chance - Random generator helper for JavaScript）在 Node.js 环境下的完整接入流程：从 npm/yarn 安装、CommonJS 与 ES6 两种模块引入方式，到 require("chance").Chance() 便捷实例化写法，并结合仓库源码与测试用例，深入剖析 Chance 的模块导出机制、构造函数与种子机制。读完本文，你将能在 Node.js 项目中熟练安装并调用 Chance 生成字符串、数字、姓名、地址等各类随机数据，还能利用种子实现可复现的随机序列。

一、Chance 是什么，为什么需要在 Node.js 中接入

Chance 是一个专门为 JavaScript 设计的随机数据生成辅助库。根据仓库 README.md 的描述，它能在单文件内生成随机数字、字符、字符串、姓名、地址、骰子乃至其他几乎所有类型的数据；其底层构建于 Mersenne Twister 伪随机数生成器之上，因此可以通过种子（seed）实现序列的可复现性。

虽然 Chance 同样支持浏览器环境（参见 docs/usage/browser.md），但在 Node.js 服务端开发、接口 Mock、单元测试、批量数据填充等场景中，通过包管理器引入 Chance 是最常见、最规范的做法。本文档即官方对 Node.js 用法的说明。

二、安装 Chance

根据 docs/usage/node.md，在 Node.js 项目中使用 Chance 需要先通过包管理器安装。当前仓库 package.json 记录的版本为 1.1.13，包名即 chance，入口文件为 ./chance.js。

2.1 使用 npm 安装

npm install chance

该命令会把 Chance 安装到当前项目的 node_modules 中，并将其写入 dependencies 依赖清单。安装完成后，即可通过模块系统引入。

2.2 使用 yarn 安装

如果你的项目使用 yarn 作为包管理器，可以执行等价命令：

yarn add chance

两种方式安装的是同一个包，仅在依赖管理工具上有所区别。仓库根目录的 yarn.lock 文件正是本项目自身使用 yarn 管理依赖的证据。

三、在 Node.js 应用中引入并实例化 Chance

安装完成后，即可在应用代码中加载 Chance。官方文档给出了两种主流模块体系的写法。

3.1 CommonJS 方式（require）

// Load Chance
var Chance = require("chance");

// Instantiate Chance so it can be used
var chance = new Chance();

// Use Chance here.
var my_random_string = chance.string();

要点说明：

• require("chance") 返回的是 Chance 构造函数本身（而非实例），因此需要再执行 new Chance() 来创建实例；
• 创建实例后，即可直接调用实例方法，如 chance.string() 生成随机字符串；
• 同一进程中可以创建多个互不影响的实例。

3.2 ES6 方式（import）

在启用了 ES Module 的项目（如使用 Babel 转译或 "type": "module" 的现代 Node.js 项目）中，可以使用 import 语法：

// Load Chance
import Chance from "chance";

// Instantiate Chance so it can be used
const chance = new Chance();

// Use Chance here.
const my_random_string = chance.string();

注意：这里的默认导出（default export）同样是 Chance 构造函数，实例化方式与 CommonJS 完全一致。

3.3 便捷写法：require("chance").Chance()

自版本 0.5.5 起，官方额外提供了一种“加载即实例化”的便捷写法，省去手动 new 的步骤：

// Load and instantiate Chance
var chance = require("chance").Chance();

// Use Chance here.
var my_random_string = chance.string();

这种写法之所以可行，可以从仓库源码 chance.js 的模块导出部分得到印证：

// CommonJS module
if (typeof exports !== 'undefined') {
    if (typeof module !== 'undefined' && module.exports) {
        exports = module.exports = Chance;
    }
    exports.Chance = Chance;
}

也就是说，chance 包同时导出了两个东西：

• module.exports = Chance：默认导出即为构造函数，支持 require("chance") 与 import Chance from "chance"；
• exports.Chance = Chance：将构造函数挂到 Chance 属性上，因此 require("chance").Chance 拿到的就是构造函数本身。

而 require("chance").Chance() 之所以能不带 new 直接调用，则得益于构造函数内部的保护逻辑（chance.js）：

function Chance (seed) {
    if (!(this instanceof Chance)) {
        if (!seed) { seed = null; } // handle other non-truthy seeds, as described in issue #322
        return seed === null ? new Chance() : new Chance(seed);
    }
    // ...
}

当 Chance() 被当作普通函数（而非构造函数）调用时，this instanceof Chance 为假，函数会内部自动转调 new Chance(...) 并把实例返回。这一设计让便捷写法与常规写法在结果上完全等价。

四、实例化时的种子（seed）机制：让随机序列可复现

在 Node.js 中接入 Chance 后，一个非常实用的能力是使用种子创建可复现的随机序列，这与仓库 README 中“built on top of a Mersenne Twister so it can generate these things with repeatability, if desired”的描述一致。完整说明见 docs/usage/seed.md，下面给出 Node.js 场景下的三种典型用法。

4.1 数字种子

var chance1 = new Chance(12345);
var chance2 = new Chance(12345);

// 两个实例生成完全相同的数值序列
console.log(chance1.random());
console.log(chance2.random());

相同的种子意味着相同的 Mersenne Twister 初始状态，因此两次实例化后逐次调用会得到一致的序列——这对测试、演示、A/B 对照都很有价值。

4.2 字符串种子

种子也可以是字符串：

var chance1 = new Chance("foo");
var chance2 = new Chance("bar");

// 不同种子生成不同结果
console.log(chance1.random());
console.log(chance2.random());

从源码 chance.js 可以看到，构造函数会把每个字符串参数按字符编码做哈希累加，再合并进种子数值，最终交给 Mersenne Twister 使用。

4.3 多参数种子

还可以传入多个参数共同组成种子：

var chance1 = new Chance("hold", "me", "closer");
var chance2 = new Chance("tony", "danza");
var chance3 = new Chance("hold", "me", "closer");

// chance1 与 chance2 不同
console.log(chance1.random());
console.log(chance2.random());

// chance3 与 chance1 相同（参数完全一致）
console.log(chance3.random());

这种多参数组合方式常用于为不同业务场景构造互不干扰且可复现的随机源。相关行为在测试 test/test.basic.js 中有成体系的验证，例如：相同种子（数字与字符串）产出相同序列、不同种子产出不同序列、new Chance(() => 123) 可用自定义函数完全接管随机数生成等。

五、不传种子的默认行为与 Node 环境的适配细节

• 默认随机：new Chance() 不传任何参数时，Mersenne Twister 使用空种子初始化，每次运行生成的序列都不同（测试 test/test.basic.js 中 Chance() does not return repeatable results if no seed provided 一节对此有专门断言）。
• Node 环境的 Buffer 适配：Chance 内部需要 Base64 编码能力时，会优先使用浏览器全局 btoa；在 Node.js 环境下则回退到 Buffer 实现（见 chance.js 的 determineBase64Encoder）。这意味着在 Node.js 中，涉及 Base64 的功能（如部分 hash 类生成器）无需额外 polyfill，开箱即用。
• Worker 与浏览器全局：源码末尾还通过 importScripts 与 window 判断，支持 Web Worker 与浏览器全局（window.Chance、window.chance）环境（chance.js），Node.js 场景下主要由前述 CommonJS 分支承担导出。

六、Node.js 实战示例

将以上内容组合起来，一个典型的 Node.js 脚本如下：

// CommonJS 方式
const Chance = require("chance");
const chance = new Chance();

// 基础随机数据
console.log(chance.string());            // 随机字符串
console.log(chance.integer({ min: 1, max: 100 })); // 1~100 随机整数
console.log(chance.natural());           // 非负整数
console.log(chance.name());              // 随机姓名
console.log(chance.address());           // 随机地址
console.log(chance.email());             // 随机邮箱

// 用种子构造可复现实例（如接口 Mock 的固定数据源）
const seeded = new Chance(2024);
console.log(seeded.string());

若希望输出完全一致，仅需将 new Chance(2024) 中的种子固定并复用同一实例。

七、验证安装与引入是否成功

安装与引入是否正确，可以用仓库自带的测试体系作为参照：项目测试脚本 "test": "ava"（见 package.json），全部用例位于 test 目录。例如 test/test.basic.js 顶部正是以 ES6 方式引入源码后实例化：

import Chance from '../chance.js'
const chance = new Chance()

在你自己项目的 Node.js 环境中，可通过一行命令快速验证：

node -e "const chance = require('chance').Chance(); console.log(chance.string());"

若输出一个随机字符串，则说明安装、引入与实例化链路全部正常。

八、常见问题小结

问题	原因与解决办法
require("chance") 返回的不是实例	Chance 导出的是构造函数，必须 new Chance() 或使用 require("chance").Chance() 便捷写法
多次 new Chance() 结果完全相同	传入了相同种子，属于可复现设计；去掉种子参数即可获得不重复序列
使用 import Chance from "chance" 报错	确认项目模块体系支持 ES Module，或改用 CommonJS 的 require 写法
版本说明	当前仓库 package.json 中版本为 1.1.13，源码头部注释标注 1.1.12，实际以包发布版本为准

本文所有安装命令、引入方式与种子用法均继承自 docs/usage/node.md，并结合 chance.js、package.json、test/test.basic.js 等仓库文件完成了源码级佐证，可在 Node.js 项目中直接照此实践。