# @haraka/email-address 中文文档

规范地址：https://npmcn.com/package/%40haraka/email-address/

版本：3\.1\.7
npm 元数据更新时间：2026-11-03T04:00:36.847Z
中文译文更新时间：2026-11-17T09:34:53.767Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：147 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-05-14T19:28:17.573Z
- 最新版本发布：2026-11-03T04:00:36.480Z
- 近 30 天下载量：171111（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

RFC-5321 信封和 RFC-5322 电子邮件地址解析器

## 安装

```sh
npm install @haraka/email-address
```

也可以使用：`pnpm add @haraka/email-address`、`yarn add @haraka/email-address`、`bun add @haraka/email-address`

## README

[![Build Status](https://github.com/haraka/email-address/actions/workflows/ci.yml/badge.svg)](https://github.com/haraka/email-address/actions/workflows/ci.yml) [![Coverage Status](https://codecov.io/github/haraka/email-address/branch/main/graph/badge.svg?token=fbar73t4OV)](https://codecov.io/github/haraka/email-address)

# @haraka/电子邮件地址

一个高性能的零依赖电子邮件地址解析器和电子邮件地址验证器 **简单**, SMTP 软件 **信封** (RFC 5321和电子邮件) **页眉** (RFC 5322/6532)格式。 作为无害环境管理和CJS的双重出版物使用 `import` 或者说 `require`。 。 。 .

不遵守严格RFC但包括宽大 [邮递](https://en.wikipedia.org/wiki/Robustness_principle) 选项。 最佳级 [O(n) 语](https://stackoverflow.com/questions/487258/what-is-a-plain-english-explanation-of-big-o-notation) 业绩([基准](https://npmcn.com/package/%40haraka/email-address/PERFORMANCE.md)) (中文(简体) ).

```js
parseEnvelope('<from@example.com>') // → Address
parseHeader('"Alice" <a@x>, "Bob" <b@x>') // → Address[]
parseHeader('Friends: a@x, b@x;') // → [Group]
```

信封侧柄 `<>`, (中文(简体) ), `<Postmaster>`,点原子和引用的地方部分, IPv4/IPv6地址字元和IDN(U-lables → punycode). 页眉侧会添加显示名称,注释(包括嵌入),折叠白空间,组语法,过时 制作真实世界的邮件仍然会发出.

## 安装

```sh
npm install @haraka/email-address
```

## 使用量

无害环境管理和CJS两个切入点都暴露出一个相同的 `Address` 课.

### 信封

```js
import { Address, parseEnvelope } from '@haraka/email-address'

const addr = parseEnvelope('<user@example.com>')
addr.user // 'user'
addr.host // 'example.com'
addr.address // 'user@example.com'
addr.format() // '<user@example.com>'
addr.isNull() // false

// The class form is preserved for back-compat with v3:
new Address('<user@example.com>').format() // '<user@example.com>'
```

### 页眉

`parseHeader` 接受全套标题制作——命名添加器, 添加- spec, 地址列表, 以及组 。 返回总是一个阵列, 混合 `Address` 财务报告和审定财务报表 `Group` 按文档顺序排列.

```js
import { parseHeader, parseFrom, Group } from '@haraka/email-address'

const list = parseHeader(
  '"Alice Smith" <alice@example.com>, bob@example.com (Bob), ' +
    'Friends: c@example.com, d@example.com;',
)

for (const entry of list) {
  if (entry instanceof Group) {
    console.log('group:', entry.phrase, entry.addresses.length, 'members')
  } else {
    console.log(entry.phrase, entry.address, entry.name())
  }
}

// Header-shaped shortcuts:
parseFrom('Travis CI <builds@travis-ci.org>') // → Address[]
parseSender('"Anne, PMPM" <info@x.example>') // → Address
parseReplyTo('=?utf-8?Q?Anne?= <info@x.example>') // → Address[]
```

### 平面地址验证(网表、通用)

当您只需要“ 这是有效的电子邮件地址 ” — 注册表格、 联系页、 CSV 导入项 — 使用 `parseAddress` (在错误输入上)或 `isValid` (返回布尔) 他们拒绝任何不光彩的东西 `local@domain`:角括号,注释,显示姓名,地址列表,以及组都失败.

```js
import { parseAddress, isValid } from '@haraka/email-address'

isValid('user@example.com') // true
isValid('<user@example.com>') // false  (angle brackets are envelope-only)
isValid('Alice <a@example.com>') // false  (display names are header-only)
isValid('not-an-email') // false

// Strict, RFC-conformant — "user@example" (no TLD) is valid by default:
isValid('user@localhost') // true

// Web-form preset: require a TLD:
isValid('user@localhost', { requireTLD: true }) // false
isValid('user@example.com', { requireTLD: true }) // true

// Throwing variant — returns an Address when valid:
const a = parseAddress('first.last@example.com')
a.user // 'first.last'
a.host // 'example.com'
```

### 司法理事会

```js
const { Address, parseEnvelope, parseHeader, Group } = require('@haraka/email-address')

parseEnvelope('<u@example.com>').format()
parseHeader('"Alice" <a@x>')[0].phrase // 'Alice'
```

两种样式在 [`examples/esm.mjs`](https://npmcn.com/package/%40haraka/email-address/examples/esm.mjs) 财务报告和审定财务报表 [`examples/cjs.cjs`](https://npmcn.com/package/%40haraka/email-address/examples/cjs.cjs);每个打印解析字段,用于同一组输入.

对于国际化地址,解析器保留了原始的U-label形式并懒散地暴露出A-label(punycode)形式:

```js
const addr = new Address('<δοκιμή@παράδειγμα.gr>')
addr.user // 'δοκιμή'
addr.original_host // 'παράδειγμα.gr'
addr.host // 'xn--hxajbheg2az3al.gr'
addr.is_utf8 // true
addr.format(true) // '<δοκιμή@xn--hxajbheg2az3al.gr>'
```

### 模块布局

包裹 `exports` 映射自动解析到右侧文件 :

| 消费者风格 | 决定 | 页:1 |
| --- | --- | --- |
| `import { Address } from '@haraka/email-address'` | `index.js` | 本土无害环境管理;犬类来源. |
| `require('@haraka/email-address')` | `dist/cjs/index.cjs` | 自动生成 CJS 镜像树 . |
| 类型脚本 | `index.d.ts` | 不论进入点,类型相同. |

## API 密码

### 解析器

| 函数 | 回返 | 说明 |
| --- | --- | --- |
| `parseEnvelope(input, opts?)` | `Address` | RFC-5321 单一信封地址(`MAIL FROM:` 编号 : `RCPT TO:`) (中文(简体) ). |
| `parseHeader(input, opts?)` | `(Address | Group)[]` | RFC-5322头值. 默认 `startAt = 'address-list'`。 。 。 . |
| `parseFrom(input)` | `(Address | Group)[]` | `parseHeader(input, { startAt: 'from' })`。 。 。 . |
| `parseSender(input)` | `Address` | `parseHeader(input, { startAt: 'sender' })[0]` —— 说 `Sender:` 按语法是单位地址. |
| `parseReplyTo(input)` | `(Address | Group)[]` | `parseHeader(input, { startAt: 'reply-to' })`。 。 。 . |
| `new Address(envelope, opts?)` | `Address` | 后相兼容构造器——等同 `parseEnvelope`。 。 。 . |
| `new Address(user, host, opts?)` | `Address` | 在不解析的情况下从部分中构建地址 . |

### 信封选项

| 选项 | 类型 | 默认 | 效果 |
| --- | --- | --- | --- |
| `postel` | `boolean` | `false` | 你接受的东西要自由 何时 `true`: (1) 畸形 `[IPv6:…]` (b) 256-oct RFC 5321 §4.5.3.1.3 路径限制和64-octet §4.5.3.1.1 局部部分限制提高到998-octet SMTP文本行上限(§4.5.3.1.6) |

### 页眉选项

| 选项 | 类型 | 默认 | 效果 |
| --- | --- | --- | --- |
| `startAt` | `'address-list' | 'from' | 'sender' | 'reply-to' | 'mailbox' | 'mailbox-list' | 'group' | 'angle-addr' | 'address'` | `'address-list'` | RFC-5322开始生产 主要用于 `parseFrom` 编号 : `parseSender` 编号 : `parseReplyTo` 包装. |
| `allowAtInDisplayName` | `boolean` | `true` | 接受 `@` 内部显示名称——在现实世界中常见 `From:` 数值 `foo@example <foo@example.com>`。 。 。 . |
| `allowCommaInDisplayName` | `boolean` | `false` | 接受 `,` 内显示名称。 默认关闭,因为它打破 `,`\- 分开的地址列表语法. |
| `postel` | `boolean` | `false` | 你接受的东西要自由 启用两个 RFC-5322 § 4.4 obs- \* 生产 : **本地边** (多词的本地部分,例如: `"foo"."bar"@x.com`和 **obs- mbox 列表** 无效条目( e)`a@x, , b@y`,在组合中指向或中间逗号). |

### `Address` 属性

| 财产 | 说明 |
| --- | --- |
| `user` | 当地部分为书面(案件保存,引文保存). |
| `host` | 域名形式:小写,U-标签转换为A-标签(punycode). |
| `original_host` | 成文域:大小写保存,U-标签保存. |
| `original` | 完整的输入字符串 . |
| `is_utf8` | `true` 何时 **无论是** 本地部分或域包含非ASCII(RFC 6531). 不设. |
| `address` | `user@host` 使用 `original_host` 因此,案件被保留下来。 唯读取出. |
| `phrase` | 从页眉解析显示名称 。 信封分隔地址的空字符串 . |
| `comment` | 轨迹 `(…)` 从页眉中解析 。 信封分隔地址的空字符串 . |
| `group` | 关闭 `Group` 当解析在一个, 否则 `null`。 。 。 . |

### `Address` 方法

| 方法 | 回返 |
| --- | --- |
| `isNull()` | `true` 用于无倒向路径的(`<>` / 空输入). |
| `format(use_punycode = false)` | 冠状. 信封 : `<user@host>`。标题 : `Phrase <user@host> (Comment)`与 `use_punycode = true`,圆码 `host` 已使用. |
| `name()` | 从 Heuristic 个人姓名提取 `phrase` 编号 : `comment` 编号 : `address`. 回归 `''` 当找不到可用文件时. |
| `toString()` | 与 `format()`。 。 。 . |

### `Group`

`Group` 实例出现在 `parseHeader` 输入时的结果 包含类似 `Friends: a@x, b@x;`. 每个成员 `Address` 已经 联合国 `.group` 字段指向附件 `Group`。 。 。 .

| 外地/方法 | 说明 |
| --- | --- |
| `phrase` | 组显示名 . |
| `addresses` | `Address[]` ——按文件顺序分组成员. |
| `format()` | `phrase:addr1,addr2,…;` 按RFC 5322§3.4进行渲染. |
| `name()` | 从 Heuristic 个人姓名提取 `phrase`。 。 。 . |

### 姓名处理公用事业

从 `address-rfc2822` 用于源兼容性 :

| 函数 | 说明 |
| --- | --- |
| `nameCase(s)` | 带有Mc/O'和罗马数字的特案标题`level iii support → Level III Support`) (中文(简体) ). |
| `isAllLower(s)` 编号 : `isAllUpper(s)` | 用于大小写检测的助手 `nameCase`。 。 。 . |
| `extractName(phrase, address?)` | 背后的热情 `Address.prototype.name()` ——曝出可直接使用. |

## 遵守标准

此解析器的目标是默认严格符合SMTP信封语法. 下表跟踪每个相关的RFC以及模块对此所做的.

| RFC (RFC ) (法语) | 议题 | 状态 |
| --- | --- | --- |
| [RFC 821 (韩语)](https://www.rfc-editor.org/rfc/rfc821) 编号 : [第2821号](https://www.rfc-editor.org/rfc/rfc2821) 编号 : [第5321号](https://www.rfc-editor.org/rfc/rfc5321) | SMTP 信封地址 | **相会相会.** 执行§4.1.2(邮箱、路径、源路由、ADL)、§4.1.3(地址文字)和§4.5.3.1的长度限制. |
| [RFC 5321 第4.1.2节](https://www.rfc-editor.org/rfc/rfc5321) | 地方部分(点弦,引自) | **相会相会.** 两种表格都进行了解析;保存了大小写;引用了页(`\x`已接受. |
| [RFC 5321 第4.1.3节](https://www.rfc-editor.org/rfc/rfc5321) | IPv4 地址文字 | **相会相会.** 严格octet验证(0-255,无前置0). |
| [RFC 5321 第4.1.3节](https://www.rfc-editor.org/rfc/rfc5321) | IPv6 地址文字 | **符合规定(严格).** 这个 `IPv6:` 标记是对 IPv6- full / IPv6-comp / IPv6v4- full / IPv6v4-comp 生产进行验证. 这个 `postel: true` 选项选择返回到后退. |
| [RFC 5321 第4.1.2节](https://www.rfc-editor.org/rfc/rfc5321) | 源路线/ ADL | **差异(已丢弃).** 源路由分析正确但静态投放;只有最后的邮箱被保留. RFC 5321 调取出源路由; 需要时从外部保存. |
| [RFC 5321 第4.5.3.1.1节](https://www.rfc-editor.org/rfc/rfc5321) | 64个地方部分 | **相会相会.** 字节被计算为UTF-8 octets. `postel: true` 将上限提高到998octets(第4.5.3.1.6节SMTP文本行上限). |
| [RFC 5321 第4.5.3.1.2节](https://www.rfc-editor.org/rfc/rfc5321) | 255-octet域名 | **相会相会.** 在任何IDN编码之前检查过了 . |
| [RFC 5321 第4.5.3.1.3节](https://www.rfc-editor.org/rfc/rfc5321) | 256-octet 路径 | **相会相会.** 在输入字符串上执行. `postel: true` 将上限提高到998octets(第4.5.3.1.6节SMTP文本行上限). |
| [RFC 1035 第2.3.4节](https://www.rfc-editor.org/rfc/rfc1035) 编号 : [RFC 5321 第4.5.3.1.1节](https://www.rfc-editor.org/rfc/rfc5321) | 63-octet标签 | **相会相会.** 如果每个子域标签的UTF-8长度超过63个octets,则会被拒绝. |
| [RFC 1123 第2.1节](https://www.rfc-editor.org/rfc/rfc1123) | 标签可能以数字开头 | **相会相会.** |
| [第3629号公约](https://www.rfc-editor.org/rfc/rfc3629) | UTF-8 八分点计数 | **相会相会.** 用途 `Buffer.byteLength(..., 'utf8')` 检查每个地方的长度. |
| [RFC 5322 (韩语)](https://www.rfc-editor.org/rfc/rfc5322) | 信件头地址语法 | **合规通过 `parseHeader`。 。 。 .** 对§3.4(名称添加、添加- spec、组、地址-列表)的递归-descent解析器,带有默认允许的§4.4过时生产(FWS周围) `@`,点点显示名称, `_` 在遗留标签中,嵌入式评论)。 信封解析仍然拒绝这些——它们只适用于信头路径. |
| [RFC 6531 (韩语)](https://www.rfc-editor.org/rfc/rfc6531) | SPTPUTF8——国际化地址 | **协和 (基础).** 本地部分和域均接受非ASCII代码点. `is_utf8` 设定为 **无论是** 侧面包含非ASCII。 Unicode 正常化( NBC) 是 **没有** 执行. |
| [RFC 5890 (法语)](https://www.rfc-editor.org/rfc/rfc5890) 编号 : [第5891号](https://www.rfc-editor.org/rfc/rfc5891) 编号 : [第5892号](https://www.rfc-editor.org/rfc/rfc5892) 编号 : [UTS-46号](https://www.unicode.org/reports/tr46/) | IDNA2008 / UTS-46 (英语) | **协和会 (通过平台).** IDN 转换使用节点的内置 `url.domainToASCII`,它执行UTS-46(IDNA2008有过渡规则). 无效的 IDN 标签 . |
| [RFC 5893 (法语)](https://www.rfc-editor.org/rfc/rfc5893) | Bidi(从右到左)规则 | **继承自 `domainToASCII`。 。 。 .** 未由本模块单独执行 . |
| [RFC 5198 (法语)](https://www.rfc-editor.org/rfc/rfc5198) | 网- Unicode (NFC) (NFC) | **差额(未正常化).** 解析器保留了调用者提供的形式. 如果需要在编码上进行比特等同的比较,则将外部规范化. |

## 许可证

麻省理工学院.

## 常见问题

### @haraka/email-address 是什么？

RFC-5321 信封和 RFC-5322 电子邮件地址解析器

### 如何安装 @haraka/email-address？

在项目目录运行 npm install @haraka/email-address，或使用 pnpm add / yarn add / bun add。

### @haraka/email-address 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @haraka/email-address 支持 ESM 还是 CommonJS？

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

### @haraka/email-address 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @haraka/email-address 可以商用吗？

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

### @haraka/email-address 的下载量有多少？

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

### @haraka/email-address 还在维护吗？

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

