# @adraffy/ens-normalize 中文文档

规范地址：https://npmcn.com/package/%40adraffy/ens-normalize/

版本：1\.11\.1
npm 元数据更新时间：2025-09-18T19:40:31.444Z
中文译文更新时间：2026-11-05T16:50:30.958Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：456 kB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2021-11-21T23:31:31.034Z
- 最新版本发布：2025-09-18T19:40:31.258Z
- 近 30 天下载量：23198992（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 0 个）

## 中文简介

Ethereum 名称服务( ENS) 名称规范化器

## 安装

```sh
npm install @adraffy/ens-normalize
```

也可以使用：`pnpm add @adraffy/ens-normalize`、`yarn add @adraffy/ens-normalize`、`bun add @adraffy/ens-normalize`

## README

# 规范化.js

零依赖性 [Ethereum 名称服务](https://ens.domains/) (ENS)名称"常态".

`npm i @adraffy/ens-normalize` [✓](https://www.npmjs.com/package/@adraffy/ens-normalize)

-   QQ 跟踪 [**ENSIP-15 (英语)**: ENS 名称规范化标准](https://docs.ens.domains/ensip/15)
    -   统一码 : [`17.0.0`](https://npmcn.com/package/%40adraffy/ens-normalize/derive/data/17.0.0/) • 批准: [`47`](https://npmcn.com/package/%40adraffy/ens-normalize/derive/data/CLDR-47/)
    -   其他执行:
        -   蟒蛇—— [名称hash/**普通化-平通**](https://github.com/namehash/ens-normalize-python)
        -   脏- [7个/**规范化 - r**](https://github.com/sevenzing/ens-normalize-rs)
        -   齐格.. [evmts/ (单位:千美元)**z - 感通性**](https://github.com/evmts/z-ens-normalize)
        -   C # - 开始吧.. [严重/**ENSNORMORICE.cs (英语)**](https://github.com/adraffy/ENSNormalize.cs)
        -   爪哇语 - [严重/**(原始内容存档于2019-10-21) (英语). ENSNormarize.java**](https://github.com/adraffy/ENSNormalize.java)
        -   挥 -- -- [严重/**ENSNORMORIZE.swift (英语)**](https://github.com/adraffy/ENSNormalize.swift)
        -   开始.. [严重/**正常运行**](https://github.com/adraffy/go-ens-normalize)
        -   挥 -- -- [严重/**ENSNORMORIZE.swift (英语)**](https://github.com/adraffy/ENSNormalize.swift)
    -   先前执行:
        -   爪哇语- [内域/**名称**](https://github.com/ensdomains/eth-ens-namehash)
    -   [ENSIP-1报告细目](https://adraffy.github.io/ens-norm-tests/test-breakdown/output-20230226/)
-   传球 **100%** [ENSIP-15 验证测试](https://adraffy.github.io/ens-normalize.js/test/validate.html)
-   传球 **100%** [Unicode 规范化测试](https://adraffy.github.io/ens-normalize.js/test/report-nf.html)
-   已缩小的文件大小 :
    -   [`29KB`](https://npmcn.com/package/%40adraffy/ens-normalize/dist/index-xnf.min.js) ——本地NFC通过 [nf-native.js (英语)](https://npmcn.com/package/%40adraffy/ens-normalize/src/nf-native.js) 使用 `String.normalize()` ⚠️
    -   [`38KB` **默认**](https://npmcn.com/package/%40adraffy/ens-normalize/dist/index.min.js) ——自定义 NFC 通过 [无](https://npmcn.com/package/%40adraffy/ens-normalize/src/nf.js)
    -   [`44KB`](https://npmcn.com/package/%40adraffy/ens-normalize/dist/all.min.js) _所有的东西!_ ——自定义NFC+子图书馆: [编.js](https://npmcn.com/package/%40adraffy/ens-normalize/src/parts.js), (中文(简体) ), [乌特尔斯.js](https://npmcn.com/package/%40adraffy/ens-normalize/src/utils.js)
-   包含 Apps :
    -   [**解析器Demo**](https://adraffy.github.io/ens-normalize.js/test/resolver.html) ⭐
    -   [支持的爱莫吉](https://adraffy.github.io/ens-normalize.js/test/emoji.html)
    -   [字符查看器](https://adraffy.github.io/ens-normalize.js/test/chars.html)
    -   [混淆解释器](https://adraffy.github.io/ens-normalize.js/test/confused.html)
-   相关项目:
    -   [最近的.eth登记](https://raffy.antistupid.com/eth/ens-regs.html) 二. 支助 [续](https://raffy.antistupid.com/eth/ens-renews.html) 二. 支助 [过期](https://raffy.antistupid.com/eth/ens-exp.html)
    -   [标签数据库](https://github.com/adraffy/ens-labels/) 二. 支助 [标签- 1](https://adraffy.github.io/ens-labels/demo.html) 二. 支助 [野蛮武力](https://raffy.antistupid.com/eth/ens-brute.html)
    -   [Emoji 频率探索器](https://raffy.antistupid.com/eth/ens-emoji-freq.html)
    -   [严重/**punycode.js (英语)**](https://github.com/adraffy/punycode.js/) 二. 支助 [Punycode 编码器](https://adraffy.github.io/punycode.js/test/demo.html)
    -   [严重/**(中文(简体) )**](https://github.com/adraffy/keccak.js/) 二. 支助 [凯查克・哈舍](https://adraffy.github.io/keccak.js/test/demo.html)
    -   [严重/**emoji.js (英语)**](https://github.com/adraffy/emoji.js/) 二. 支助 [Emoji 解析器](https://adraffy.github.io/emoji.js/test/demo.html)
    -   下方更多链接 [解析器Demo](https://adraffy.github.io/ens-normalize.js/test/resolver.html)

```js
import {ens_normalize} from '@adraffy/ens-normalize'; // or require()
// browser: https://cdn.jsdelivr.net/npm/@adraffy/ens-normalize@latest/dist/index.min.mjs (or .cjs)

// *** ALL errors thrown by this library are safe to print ***
// - characters are shown as {HEX} if should_escape()
// - potentially different bidi directions inside "quotes"
// - 200E is used near "quotes" to prevent spillover
// - an "error type" can be extracted by slicing up to the first (:)
// - labels are middle-truncated with ellipsis (…) at 63 cps

// string -> string
// throws on invalid names
// output ready for namehash
let normalized = ens_normalize('RaFFY🚴‍♂️.eTh');
// => "raffy🚴‍♂.eth"

// note: does not enforce .eth registrar 3-character minimum
```

用完全合格的emoji格式化名称 :

```js
// works like ens_normalize()
// output ready for display
let pretty = ens_beautify('1⃣2⃣.eth'); 
// => "1️⃣2️⃣.eth"

// note: normalization is unchanged:
// ens_normalize(ens_beautify(x)) == ens_normalize(x)
```

将名称片断规范化 [子字符串搜索](https://npmcn.com/package/%40adraffy/ens-normalize/test/fragment.js)数字 :

```js
// these fragments fail ens_normalize() 
// but will normalize fine as fragments
let frag1 = ens_normalize_fragment('AB--');    // expected error: label ext
let frag2 = ens_normalize_fragment('\u{303}'); // expected error: leading cm
let frag3 = ens_normalize_fragment('οо');      // expected error: mixture
```

基于输入的符号化 :

```js
// string -> Token[]
// never throws
let tokens = ens_tokenize('_R💩\u{FE0F}a\u{FE0F}\u{304}\u{AD}./');
// [
//     { type: 'valid', cps: [ 95 ] }, // valid (as-is)
//     {
//         type: 'mapped', 
//         cp: 82,         // input
//         cps: [ 114 ]    // output
//     }, 
//     { 
//         type: 'emoji',
//         input: Emoji(2) [ 128169, 65039 ],  // input 
//         emoji: [ 128169, 65039 ],           // fully-qualified
//         cps: Emoji(1) [ 128169 ]            // output (normalized)
//     },
//     {
//         type: 'nfc',
//         input: [ 97, 772 ],  // input (before nfc)
//         cps: [ 257 ],        // output (after nfc)
//         tokens0: [           // tokens (before nfc)
//             { type: 'valid', cps: [ 97 ] },
//             { type: 'ignored', cp: 65039 },
//             { type: 'valid', cps: [ 772 ] }
//         ],
//         tokens: [            // tokens (after nfc)
//             { type: 'valid', cps: [ 257 ] }
//         ]
//     },
//     { type: 'ignored', cp: 173 },
//     { type: 'stop', cp: 46 },
//     { type: 'disallowed', cp: 47 }
// ]

// note: if name is normalizable, then:
// ens_normalize(ens_tokenize(name).map(token => {
//     ** convert valid/mapped/nfc/stop to string **
// }).join('')) == ens_normalize(name)
```

基于输出的符号化 :

```js
// string -> Label[]
// never throws
let labels = ens_split('💩Raffy.eth_');
// [
//   {
//     input: [ 128169, 82, 97, 102, 102, 121 ],  
//     offset: 0, // index of codepoint, not substring index!
//                // (corresponding length can be inferred from input)
//     tokens: [
//       Emoji(2) [ 128169, 65039 ],   // emoji
//       [ 114, 97, 102, 102, 121 ]    // nfc-text
//     ],
//     output: [ 128169, 114, 97, 102, 102, 121 ],
//     emoji: true,
//     type: 'Latin'
//   },
//   {
//     input: [ 101, 116, 104, 95 ],
//     offset: 7,
//     tokens: [ [ 101, 116, 104, 95 ] ],
//     output: [ 101, 116, 104, 95 ],
//     error: Error('underscore allowed only at start')
//   }
// ]
```

生成一个被排序的(被beauized)支持的emoji编码点数组 :

```js
// () -> number[][]
let emojis = ens_emoji();
// [
//     [ 2764 ],
//     [ 128169, 65039 ],
//     [ 128105, 127997, 8205, 9877, 65039 ],
//     ...
// ]
```

确定一个字符是否不应被直接打印 :

```js
// number -> bool
should_escape(0x202E); // eg. RIGHT-TO-LEFT OVERRIDE => true
```

确定字符是否为组合标记 :

```js
// number -> bool
is_combining_mark(0x20E3); // eg. COMBINING ENCLOSING KEYCAP => true
```

将代码点格式化为打印安全字符串 :

```js
// number[] -> string
safe_str_from_cps([0x300, 0, 32, 97]); // "◌̀{00} a"
safe_str_from_cps(Array(100).fill(97), 4); // "aa…aa" => middle-truncated
```

## 构建

-   `git clone` 那么,这个雷波 `npm install`
-   执行指令 [/贬损/](https://npmcn.com/package/%40adraffy/ens-normalize/derive/) 生成数据文件
    -   `npm run derive`
        -   [spec.json (英语)](https://npmcn.com/package/%40adraffy/ens-normalize/derive/output/spec.json)
        -   [尼夫·杰森(签名)](https://npmcn.com/package/%40adraffy/ens-normalize/derive/output/nf.json)
        -   [nf-tests.json (英语)](https://npmcn.com/package/%40adraffy/ens-normalize/derive/output/nf-tests.json)
-   `npm run make` ——从压缩数据文件 [/衍生/产出/](https://npmcn.com/package/%40adraffy/ens-normalize/derive/output/)
    -   [包含 -ens.js](https://npmcn.com/package/%40adraffy/ens-normalize/src/include-ens.js)
    -   [包含-nf.js](https://npmcn.com/package/%40adraffy/ens-normalize/src/include-nf.js)
    -   [包含版本.js](https://npmcn.com/package/%40adraffy/ens-normalize/src/include-versions.js)
-   执行指令 [/验证/](https://npmcn.com/package/%40adraffy/ens-normalize/validate/) 生成验证测试
    -   `npm run validate`
        -   [测试.json](https://npmcn.com/package/%40adraffy/ens-normalize/validate/tests.json)
-   `npm run test` 进行验证测试
-   `npm run build` ——创建 [盘点/盘点](https://npmcn.com/package/%40adraffy/ens-normalize/dist/)
-   `npm run rebuild` - 运行上面的所有命令
-   `npm run order` ——再创建最佳组顺序并重建

## 警卫

-   [构建](https://npmcn.com/package/%40adraffy/ens-normalize/#readme-build) 比较 [包含版本.js](https://npmcn.com/package/%40adraffy/ens-normalize/src/include-versions.js)
    -   `spec_hash` —— SHA-256,第256页 [spec.json (英语)](https://npmcn.com/package/%40adraffy/ens-normalize/derive/output/spec.json) 字节
    -   `ens_hash_base64` —— SHA-256,第256页 [包含 -ens.js](https://npmcn.com/package/%40adraffy/ens-normalize/src/include-ens.js) 基数64升
    -   `nf_hash_base64` —— SHA-256,第256页 [包含-nf.js](https://npmcn.com/package/%40adraffy/ens-normalize/src/include-nf.js) 基数64升

## 常见问题

### @adraffy/ens-normalize 是什么？

Ethereum 名称服务\( ENS\) 名称规范化器

### 如何安装 @adraffy/ens-normalize？

在项目目录运行 npm install @adraffy/ens-normalize，或使用 pnpm add / yarn add / bun add。

### @adraffy/ens-normalize 支持 TypeScript 吗？

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

### @adraffy/ens-normalize 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @adraffy/ens-normalize 可以商用吗？

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

### @adraffy/ens-normalize 的下载量有多少？

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

### @adraffy/ens-normalize 还在维护吗？

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