# @contentpass/zxcvbn 中文文档

规范地址：https://npmcn.com/package/%40contentpass/zxcvbn/

版本：4\.4\.3
npm 元数据更新时间：2024-12-04T13:42:24.952Z
中文译文更新时间：2026-11-10T22:00:07.815Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40contentpass/zxcvbn
原文对照：https://npmcn.com/package/%40contentpass/zxcvbn/?lang=original
项目主页：https://github.com/contentpass/zxcvbn#readme
源码仓库：https://github.com/contentpass/zxcvbn

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.5 MB，29 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2018-01-29T10:40:30.638Z
- 最新版本发布：2018-06-13T08:16:15.848Z
- 近 30 天下载量：2904（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

现实密码强度估计

## 安装

```sh
npm install @contentpass/zxcvbn
```

也可以使用：`pnpm add @contentpass/zxcvbn`、`yarn add @contentpass/zxcvbn`、`bun add @contentpass/zxcvbn`

## README

```
_________________________________________________/\/\___________________
_/\/\/\/\/\__/\/\__/\/\____/\/\/\/\__/\/\__/\/\__/\/\________/\/\/\/\___
_____/\/\______/\/\/\____/\/\________/\/\__/\/\__/\/\/\/\____/\/\__/\/\_
___/\/\________/\/\/\____/\/\__________/\/\/\____/\/\__/\/\__/\/\__/\/\_
_/\/\/\/\/\__/\/\__/\/\____/\/\/\/\______/\______/\/\/\/\____/\/\__/\/\_
________________________________________________________________________
```

[![Build Status](https://travis-ci.org/dropbox/zxcvbn.svg?branch=master)](https://travis-ci.org/dropbox/zxcvbn) [![Sauce Test Status](https://saucelabs.com/browser-matrix/dropbox-zxcvbn.svg)](https://saucelabs.com/u/dropbox-zxcvbn)

`zxcvbn` 是一个由密码快取器启发的密码强度估计器。 通过模式匹配和保守估计,它根据美国人口普查数据,识别并权衡了30k个常见密码,常见名和姓氏,维基百科和美国电视和电影的流行英语单词,以及诸如日期等常见模式,重复(`aaa`),顺序(`abcd`),键盘模式(`qwertyuiop`),并133t说话.

考虑使用zxcvbn作为密码构成策略的算法替代方案——当网站需要最小的复杂分数来取而代之的"密码必须包含 {更低,上,数字,符号} 三等"时,它更加安全,灵活并可用.

-   **更安全**:政策往往双向失败,允许密码薄弱(`P@ssword1`)和拒绝强口令.
-   **更灵活**:zxcvbn 只要能检测出足够的复杂度,就可以使许多密码样式蓬勃发展——密码句被高度评价为足够不寻常的单词,键盘模式根据长度和转弯次数来排序,而资本化在不预测Ble时会增加更复杂.
-   **更实用**:zxcvbn是用来为提供即时反馈的简单而无规则的界面提供动力的. 除了强度估计,zxcvbn还包括了最小的,有针对性的口头反馈,可以帮助引导用户向更难猜测的密码.

关于进一步详情和动机,请参见USENIX 安保 ' 16 [论文和介绍](https://www.usenix.org/conference/usenixsecurity16/technical-sessions/presentation/wheeler)。 。 。 .

在 Dropbox 我们使用 zxcvbn ([发布注释](https://github.com/dropbox/zxcvbn/releases)) 在我们的网络,桌面,iOS和Android客户端. 如果JavaScript不为你工作,其他人则慷慨地将库移植到这些语言上:

-   [`zxcvbn-python`](https://github.com/dwolfhub/zxcvbn-python) (P
-   [`zxcvbn-cpp`](https://github.com/rianhunter/zxcvbn-cpp) (C/C++/P/JS)
-   [`zxcvbn-c`](https://github.com/tsyrogit/zxcvbn-c) (中文(简体) )
-   [`zxcvbn-rs`](https://github.com/shssoichiro/zxcvbn-rs) (鲁斯特)
-   [`zxcvbn-go`](https://github.com/nbutton23/zxcvbn-go) (开始)
-   [`zxcvbn4j`](https://github.com/nulab/zxcvbn4j) (贾瓦)
-   [`nbvcxz`](https://github.com/GoSimpleLLC/nbvcxz) (贾瓦)
-   [`zxcvbn-ruby`](https://github.com/envato/zxcvbn-ruby) (鲁比)
-   [`zxcvbn-js`](https://github.com/bitzesty/zxcvbn-js) (鲁比\[通过ExecJS\])
-   [`zxcvbn-ios`](https://github.com/dropbox/zxcvbn-ios) (目标-C)
-   [`zxcvbn-cs`](https://github.com/mickford/zxcvbn-cs) (C#.NET) (中文(简体) )
-   [`szxcvbn`](https://github.com/tekul/szxcvbn) (斯卡拉语)
-   [`zxcvbn-php`](https://github.com/bjeavons/zxcvbn-php) (菲律宾语)
-   [`zxcvbn-api`](https://github.com/wcjr/zxcvbn-api) (续)
-   [`ocaml-zxcvbn`](https://github.com/cryptosense/ocaml-zxcvbn) (OCAML 装订 `zxcvbn-c`(中文(简体) )

与其他框架的整合:

-   [`angular-zxcvbn`](https://github.com/ghostbar/angular-zxcvbn) (英语:AngularJS)

# 安装

zxcvbn检测并支援了CommonJS(节点,浏览器)和AMD(RequireJS). 如果没有这些,它就增加了一个单一功能 `zxcvbn()` 到全局命名空间.

## 鲍尔

安装 [`node`](https://nodejs.org/download/) 财务报告和审定财务报表 [`bower`](http://bower.io/) 如果你还没有.

获取 `zxcvbn`数字 :

```shell
cd /path/to/project/root
bower install zxcvbn
```

将此脚本添加到您的 `index.html`数字 :

```html
<script src="bower_components/zxcvbn/dist/zxcvbn.js">
</script>
```

为保证正确加载, 在浏览器和类型中打开 `zxcvbn('Tr0ub4dour&3')` 进入控制台.

要调取更新和错误修正 :

```shell
bower update zxcvbn
```

## 节点/ npm/ 气象JS

zxcvbn在服务器上同样工作.

```shell
$ npm install zxcvbn
$ node
> var zxcvbn = require('zxcvbn');
> zxcvbn('Tr0ub4dour&3');
```

## 要求 JS 请求

添加 [`zxcvbn.js`](https://raw.githubusercontent.com/dropbox/zxcvbn/master/dist/zxcvbn.js) 输入到您的项目( 使用弓箭、 npm 或直接下载) 并按常规导入 :

```javascript
requirejs(["relpath/to/zxcvbn"], function (zxcvbn) {
    console.log(zxcvbn('Tr0ub4dour&3'));
});
```

## 浏览/ Web 软件包

如果你在用的话 `npm` 并且已经 `require('zxcvbn')` 在你的代码里,浏览器和网络包装 应该只是工作.

```shell
$ npm install zxcvbn
$ echo "console.log(require('zxcvbn'))" > mymodule.js
$ browserify mymodule.js > browserify_bundle.js
$ webpack mymodule.js webpack_bundle.js
```

但我们建议不要通过浏览器和网络包装等工具来捆绑zxcvbn,原因有三:

-   已经消化和消化,zxcvbn仍然是几百千字节。 (相克而长出捆子大小
-   大多数站点在几页上只需要zxcvbn(注册,密码重置).
-   大多数网站不需要 `zxcvbn()` 立即装入页面; 自 `zxcvbn()` 通常为响应用户事件而调用,例如填写密码,有充足的时间获取 `zxcvbn.js` 在 html/cs/js 初始装入和制作后.

见 [业绩](https://npmcn.com/package/%40contentpass/zxcvbn/#readme-perf) 下面的一节是关于装入 zxcvbn 独立操作的提示.

切切地说,如果你想建立自己的独立,考虑对用于生成的浏览器进行微调 `dist/zxcvbn.js`数字 :

```shell
$ browserify --debug --standalone zxcvbn \
    -t coffeeify --extension='.coffee' \
    -t uglifyify \
    src/main.coffee | exorcist dist/zxcvbn.js.map >| dist/zxcvbn.js
```

-   `--debug` 在捆绑中添加内入源映射. `exorcist` 把它拉出来 `dist/zxcvbn.js.map`。 。 。 .
-   `--standalone zxcvbn` 全球出口 `zxcvbn` 当普通JS/AMD未被检测出时.
-   `-t coffeeify --extension='.coffee'` 编译 `.coffee` 改为 `.js` 在捆绑之前 这是方便的,只要它允许 `.js` 要导入的模块 `.coffee` 模块和反之。 而不是这种转变,人们也可以编集一切到 `.js` 首`npm run prepublish`)和点 `browserify` 改为 `lib` 改为 `src`。 。 。 .
-   `-t uglifyify` 通过 UglifyJS 修改捆绑,保持正确的源头映射.

## 手动安装

下载 [sxcvbn.js (英语)](https://raw.githubusercontent.com/dropbox/zxcvbn/master/dist/zxcvbn.js)。 。 。 .

添加到您的. html :

```html
<script type="text/javascript" src="path/to/zxcvbn.js"></script>
```

# 使用量

[以交互方式尝试 zxcvbn](https://dl.dropboxusercontent.com/u/209/zxcvbn/test/index.html) 可以看到这些文件在行动.

```javascript
zxcvbn(password, options={})
```

`zxcvbn()` 需要一个参数、一个密码,然后返回具有多个属性的结果对象:

```coffee
result.guesses            # estimated guesses needed to crack password
result.guesses_log10      # order of magnitude of result.guesses

result.crack_times_seconds # dictionary of back-of-the-envelope crack time
                          # estimations, in seconds, based on a few scenarios:
{
  # online attack on a service that ratelimits password auth attempts.
  online_throttling_100_per_hour

  # online attack on a service that doesn't ratelimit,
  # or where an attacker has outsmarted ratelimiting.
  online_no_throttling_10_per_second

  # offline attack. assumes multiple attackers,
  # proper user-unique salting, and a slow hash function
  # w/ moderate work factor, such as bcrypt, scrypt, PBKDF2.
  offline_slow_hashing_1e4_per_second

  # offline attack with user-unique salting but a fast hash
  # function like SHA-1, SHA-256 or MD5. A wide range of
  # reasonable numbers anywhere from one billion - one trillion
  # guesses per second, depending on number of cores and machines.
  # ballparking at 10B/sec.
  offline_fast_hashing_1e10_per_second
}

result.crack_times_display # same keys as result.crack_times_seconds,
                           # with friendlier display string values:
                           # "less than a second", "3 hours", "centuries", etc.

result.score      # Integer from 0-4 (useful for implementing a strength bar)

  0 # too guessable: risky password. (guesses < 10^3)

  1 # very guessable: protection from throttled online attacks. (guesses < 10^6)

  2 # somewhat guessable: protection from unthrottled online attacks. (guesses < 10^8)

  3 # safely unguessable: moderate protection from offline slow-hash scenario. (guesses < 10^10)

  4 # very unguessable: strong protection from offline slow-hash scenario. (guesses >= 10^10)

result.feedback   # verbal feedback to help choose better passwords. set when score <= 2.

  result.feedback.warning     # explains what's wrong, eg. 'this is a top-10 common password'.
                              # not always set -- sometimes an empty string

  result.feedback.suggestions # a possibly-empty list of suggestions to help choose a less
                              # guessable password. eg. 'Add another word or two'

result.sequence   # the list of patterns that zxcvbn based the
                  # guess calculation on.

result.calc_time  # how long it took zxcvbn to calculate an answer,
                  # in milliseconds.
```

可选 `options` 参数是一个可以包含下列可选属性的对象:

-   `user_inputs` 是一个字符串阵列, Zxcvbn 将将其作为额外的词典处理 。 这可以是您喜欢的字符串列表, 但用于来自窗体其它字段的用户输入, 如名称和电子邮件 。 这样,包含用户个人信息的密码就会受到重罚. 这个列表对特定站点词汇也有好处——Acme Brick Co.可能想要包括\['acme','brick','acmebrick'等\].
-   `feedback_messages` 是使zxcvbn的消费者能够自定义用于给用户反馈的信息的对象. 这可以用来跳过不希望作为反馈返回给用户的邮件,也可以用来修改或国际化现有的信件. 此参数中使用的密钥列表可见于 [./src/feedback.coffee (英语)](https://npmcn.com/package/%40contentpass/zxcvbn/blob/master/src/feedback.coffee#L4)。 。 。 . 例如,删除 `use_a_few_words` 反馈信息,我们称zxcvbn如下:

```javascript
zxcvbn(password, {
  feedback_messages:{
    use_a_few_words: null
  }
});
```

任何作为消息传递的假值都会让zxcvbn跳过它. 如果我们想修改这一信息或将其国际化,我们将把新信息作为以下价值:

```javascript
zxcvbn(password, {
  feedback_messages:{
    use_a_few_words: 'Usa algunas palabras, evita frases comunes'
  }
});
```

任何未发的消息 `feedback_messages` 对象将默认为应用程序中的反馈消息.

# 业绩

## 运行时间延迟

zxcvbn在人类对大多数输入的延迟感下运行:在现代浏览器/CPU上为~25 Char密码为~5-20ms;为大约100个字符的密码为~100ms. 要对真正长口令设定运行时间间隔, 请考虑发送 `zxcvbn()` 只有用户输入的前100个字符左右.

## 脚本加载间隔

`zxcvbn.js` 被捆绑并被精密化的有大约400kB gziped或820kB未被压缩,其中大部分是词典. 考虑这些提示 如果你注意到页面 负载在您的网站.

-   请确定您的服务器配置是为了压缩支持它的浏览器的静态资产 。 ()[nginx 辅导](https://rtcamp.com/tutorials/nginx/enable-gzip/), (中文(简体) ), [Apache/IIS 教程](http://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/). ) (中文(简体) )

然后尝试其中一种选择:

1.  放下枪 `<script src="zxcvbn.js">` 在关闭前的 html 结尾处标记 `</body>` 标签。 这将确保您在浏览器取回和加载前的页面加载和制作 `zxcvbn.js`。这种方法的缺点是: `zxcvbn()` 晚于列入 `<head>` 在大多数注册页面上,用户首先填写其他字段,而不是一个问题.
    
2.  如果您使用要求JS, 请尝试加载 `zxcvbn.js` 与主包分开。 需要注意的东西: `zxcvbn.js` 在等待用户输入的键盘处理器内部需要,整个脚本只有在用户按下第一个键后才能被加载,从而产生下流的延迟. 避免这一点,在页面装入时拨打您的处理器一次, 独立于用户输入, 如 `requirejs()` 早点打电话.
    
3.  使用 HTML5 [`async`](http://www.w3schools.com/tags/att_script_async.asp) 脚本属性. 下行间 : [没用的](http://caniuse.com/#feat=script-async) 在IE7-9或歌剧迷你.
    
4.  包含内含 `<script>` 内 `<head>` 同步加载 `zxcvbn.js` 在背景中。 优点超过(3):在更古老的浏览器中有效.
    

```javascript
// cross-browser asynchronous script loading for zxcvbn.
// adapted from http://friendlybit.com/js/lazy-loading-asyncronous-javascript/

(function() {

  var ZXCVBN_SRC = 'path/to/zxcvbn.js';

  var async_load = function() {
    var first, s;
    s = document.createElement('script');
    s.src = ZXCVBN_SRC;
    s.type = 'text/javascript';
    s.async = true;
    first = document.getElementsByTagName('script')[0];
    return first.parentNode.insertBefore(s, first);
  };

  if (window.attachEvent != null) {
    window.attachEvent('onload', async_load);
  } else {
    window.addEventListener('load', async_load, false);
  }

}).call(this);
```

# 发展

虫子报告和拉出请求欢迎!

```shell
git clone https://github.com/dropbox/zxcvbn.git
```

zxcvbn是用 CoffeeScript,浏览器和uglify-js来构建的. 咖啡脚本来源位于 `src`,它被编译、捆绑和精细化成 `dist/zxcvbn.js`。 。 。 .

```shell
npm run build    # builds dist/zxcvbn.js
npm run watch    # same, but quickly rebuilds as changes are made in src.
```

对于调试, 两者 `build` 财务报告和审定财务报表 `watch` 输出外部源图 `dist/zxcvbn.js.map` 这可以追溯到最初的 CoffeeScript 代码.

两个来源文件, `adjacency_graphs.coffee` 财务报告和审定财务报表 `frequency_lists.coffee`,由 python 脚本生成于 `data-scripts` 读取原始数据 `data` 目录.

用于节点开发者, 除此之外 `dist`,该zxcvbn `npm` 模块包括 `lib` 包含一个编译的目录( 隐藏于 git) `.js` 财务报告和审定财务报表 `.js.map` 每个文件 `.coffee` 内 `src`。见 `prepublish` 内 `package.json` 学习更多.

# 承认

[弹出框](https://dropbox.com/) 用于支持开源 !

马克・伯内特 释放他的10M密码 和他的2005年书, [完美的密码: 选择、 保护、 认证](http://www.amazon.com/Perfect-Passwords-Selection-Protection-Authentication/dp/1597490415)。 。 。 .

建设联合国 [英语单词的频率列表](http://en.wiktionary.org/wiki/Wiktionary:Frequency_lists) 在电视和电影中.

康科迪亚大学研究员 [严格研究密码估计](http://www.concordia.ca/cunews/main/stories/2015/03/25/does-your-password-pass-muster.html) 并推荐 zxcvbn.

还有 [(单位:千美元)](https://xkcd.com/936/) 对于灵感 :+1:: 跑:: 电池:: 心:

## 常见问题

### @contentpass/zxcvbn 是什么？

现实密码强度估计

### 如何安装 @contentpass/zxcvbn？

在项目目录运行 npm install @contentpass/zxcvbn，或使用 pnpm add / yarn add / bun add。

### @contentpass/zxcvbn 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/contentpass\_\_zxcvbn 是否存在。

### @contentpass/zxcvbn 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @contentpass/zxcvbn 可以商用吗？

@contentpass/zxcvbn 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @contentpass/zxcvbn 的下载量有多少？

根据 npm 官方下载统计，@contentpass/zxcvbn 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,904 次，日均约 97 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @contentpass/zxcvbn 还在维护吗？

最新版本 4\.4\.3 发布于 2018/06/13（8 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/01/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。