# @grml/nomadic 中文文档

规范地址：https://npmcn.com/package/%40grml/nomadic/

版本：0\.1\.1
npm 元数据更新时间：2026-09-10T21:33:57.348Z
中文译文更新时间：2026-11-17T00:52:31.707Z
软件包许可：ISC

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

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

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

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

- 包体积（解压后）：40.4 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-03T19:58:57.809Z
- 最新版本发布：2026-06-03T20:03:38.642Z
- 近 30 天下载量：125122（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

无害环境管理电子邮件正常化和与供应商认识规则(Gmail、Outlook、Yahoo、iCloud等)和完全自定义的供应商配置相适应.

## 安装

```sh
npm install @grml/nomadic
```

也可以使用：`pnpm add @grml/nomadic`、`yarn add @grml/nomadic`、`bun add @grml/nomadic`

## README

# 游牧

供应商意识 **电子邮件正常化和分类** 用于浏览器和服务器。 纯粹的无害环境管理,零运行时间依赖性,完全输入.

两个地址可以指向同一个邮箱,即使它们看起来不同. `John.Doe+news@googlemail.com` 财务报告和审定财务报表 `johndoe@gmail.com` 都送到同一个Gmail信箱. `nomadic` 将任何地址解析为单个 **犬类形态** ,并允许您为自己的提供者配置规则.

用它来 **调试** 注册, **防止** 一次性/变相重新登记, **比较** 或简单地说 **干净** 用户输入.

* * *

## 目录

-   [安装](https://npmcn.com/package/%40grml/nomadic/#readme-installation)
-   [快开始](https://npmcn.com/package/%40grml/nomadic/#readme-quick-start)
-   [为甚么教化?](https://npmcn.com/package/%40grml/nomadic/#readme-why-canonicalization)
-   [API 参考](https://npmcn.com/package/%40grml/nomadic/#readme-api-reference)
    -   [`normalizeEmail`](https://npmcn.com/package/%40grml/nomadic/#readme-normalizeemailemail-options--string)
    -   [`normalizeEmailDetailed`](https://npmcn.com/package/%40grml/nomadic/#readme-normalizeemaildetailedemail-options--normalizedemail)
    -   [`isSameEmail`](https://npmcn.com/package/%40grml/nomadic/#readme-issameemaila-b-options--boolean)
    -   [`getEmailProvider`](https://npmcn.com/package/%40grml/nomadic/#readme-getemailprovideremail-options--string--null)
    -   [`DEFAULT_PROVIDERS`](https://npmcn.com/package/%40grml/nomadic/#readme-default_providers)
-   [内建供应商](https://npmcn.com/package/%40grml/nomadic/#readme-built-in-providers)
-   [配置](https://npmcn.com/package/%40grml/nomadic/#readme-configuration)
    -   [添加自己的提供者](https://npmcn.com/package/%40grml/nomadic/#readme-add-your-own-provider)
    -   [覆盖内置提供者](https://npmcn.com/package/%40grml/nomadic/#readme-override-a-built-in-provider)
    -   [替换所有提供者](https://npmcn.com/package/%40grml/nomadic/#readme-replace-all-providers)
    -   [每个域的默认规则](https://npmcn.com/package/%40grml/nomadic/#readme-a-default-rule-for-every-domain)
    -   [选项参考](https://npmcn.com/package/%40grml/nomadic/#readme-options-reference)
-   [食谱](https://npmcn.com/package/%40grml/nomadic/#readme-recipes)
-   [边缘案件和保障](https://npmcn.com/package/%40grml/nomadic/#readme-edge-cases--guarantees)
-   [限制](https://npmcn.com/package/%40grml/nomadic/#readme-limitations)
-   [发展](https://npmcn.com/package/%40grml/nomadic/#readme-development)
-   [许可证](https://npmcn.com/package/%40grml/nomadic/#readme-license)

* * *

## 安装

```bash
npm install @grml/nomadic
```

`nomadic` 船舶作为无害环境管理`"type": "module"`) (中文(简体) ). 它在现代浏览器和节点18+运行,没有运行时间依赖性.

## 快开始

```ts
import { normalizeEmail, isSameEmail, getEmailProvider } from "@grml/nomadic";

normalizeEmail("John.Doe+newsletter@googlemail.com"); // "johndoe@gmail.com"
normalizeEmail("John.Doe+news@outlook.com");          // "john.doe@outlook.com" (dots kept)
normalizeEmail("john-shopping@yahoo.com");            // "john@yahoo.com"  (Yahoo uses '-')
normalizeEmail("Jane@Example.COM");                   // "Jane@example.com" (unknown domain: conservative)

isSameEmail("a.b@gmail.com", "ab+promo@gmail.com");   // true
getEmailProvider("x@hotmail.co.uk");                  // "microsoft"
```

## 为甚么教化?

邮件提供者应用自己的规则来决定地址到达的邮箱是:

| 行为 | 示例 | 同一个邮箱? |
| --- | :-: | :-: |
| **加/分地址标记** | `you+anything@gmail.com` - > (中文) `you@gmail.com` | 对 |
| **点不敏感** (邮件) | `y.o.u@gmail.com` - > (中文) `you@gmail.com` | 对 |
| **别名域** (邮件) | `you@googlemail.com` - > (中文) `you@gmail.com` | 对 |
| **案件敏感性** | `You@gmail.com` - > (中文) `you@gmail.com` | 对 |

`nomadic` 对每个提供者应用正确的规则并返回一个犬形字符串,因此平等的邮箱比较相等.

## API 参考

每个函数都有一个可选 `options` 对象(参见 [配置](https://npmcn.com/package/%40grml/nomadic/#readme-configuration)) (中文(简体) ).

### `normalizeEmail(email, options?) => string`

返回条形体 `email`投篮 `TypeError` 若为 `email` 不是一个字符串。 输入格式不当( 无) `@`,空的本地/域)返回后修剪并保持不变.

```ts
normalizeEmail("  Foo.Bar+spam@GMAIL.com "); // "foobar@gmail.com"
```

### `normalizeEmailDetailed(email, options?) => NormalizedEmail`

喜欢 `normalizeEmail`,但返回全部分解:

```ts
normalizeEmailDetailed("John.Doe+promo@gmail.com");
// {
//   normalized: "johndoe@gmail.com",
//   local: "johndoe",
//   domain: "gmail.com",
//   providerId: "gmail",   // null for unknown domains
//   subaddress: "promo",   // the stripped tag, or null
//   valid: true,           // does it look like a syntactically valid address?
// }
```

### `isSameEmail(a, b, options?) => boolean`

`true` 何时 `a` 财务报告和审定财务报表 `b` 与同一条条形地址正常化(即按照配置的规则将信箱交付给同一条).

```ts
isSameEmail("J.Doe+work@gmail.com", "jdoe@googlemail.com"); // true
isSameEmail("a@outlook.com", "a@hotmail.com");              // false (distinct mailboxes)
```

### `getEmailProvider(email, options?) => string | null`

返回拥有地址域名的提供者的ID,或 `null` 如果没有提供者匹配(或者输入不是一个有效的地址). 永不掷出.

```ts
getEmailProvider("a@proton.me");   // "proton"
getEmailProvider("a@example.com"); // null
```

### `DEFAULT_PROVIDERS`

只读内置数组 [`ProviderRule`](https://npmcn.com/package/%40grml/nomadic/#readme-options-reference) 对象,导出后您可以在上面检查或构建.

```ts
import { DEFAULT_PROVIDERS } from "@grml/nomadic";
DEFAULT_PROVIDERS.flatMap((p) => p.domains); // every recognized domain
```

## 内建供应商

| 编号 | 分隔符 | 删除点 | 别名域名 | 显著域 |
| --- | :-: | :-: | --- | --- |
| `gmail` | `+` | 对 | `gmail.com` | gmail.com (中文(简体) ). googlemail.com |
| `microsoft` | `+` | 没有 | 无 | \[永久失效連結\] 展望.\*,热信.\*,活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活 |
| `yahoo` | `-` | 没有 | 无 | yhoo.\*, ymail.com, 火箭邮件.com |
| `icloud` | `+` | 没有 | 无 | icloud.com (中文(简体) ). me.com (简体). mac.com |
| `fastmail` | `+` | 没有 | 无 | sastmail.com, sastmail.fm (中文(简体) ) |
| `proton` | `+` | 没有 | 无 | 质子邮件.com,质子.me, pm.me |
| `yandex` | `+` | 没有 | 无 | yandex.\*, ya.ru (英语) |
| `zoho` | `+` | 没有 | 无 | zoho.com (中文(简体) ). zohomail.com (简体) |
| `mailfence` | `+` | 没有 | 无 | (原始内容存档于2017-03-26). mailfence.com |
| `runbox` | `+` | 没有 | 无 | 运行框.com |
| `pobox` | `+` | 没有 | 无 | pobox.com (英语) |
| `tutanota` | `+` | 没有 | 无 | tuta.com (中文(简体) ). tutanota.com (简体). keemail.me |
| `posteo` | `+` | 没有 | 无 | posteo.de, posteo.net (英语) |
| `mailbox` | `+` | 没有 | 无 | 邮箱.org |
| `aol` | 无 | 没有 | 无 | aol.com. 目标.com |

所有内置提供者都小写本地部分(它们在实践中对案例不敏感).

> **未知域** 得到一个 **保守语** 处理:域已小写 本地部分为左 **未触及**电子邮件(RFC 5321)允许对案件有敏感认识的地方 各个部件和不同的邮箱不得偶然合并。 更冲动 行为与 [`defaultRule`](https://npmcn.com/package/%40grml/nomadic/#readme-a-default-rule-for-every-domain)。 。 。 .

## 配置

### 添加自己的提供者

通过额外规则 `providers`。它们由域名匹配,并优先于内置.

```ts
import { normalizeEmail, type ProviderRule } from "@grml/nomadic";

const corporate: ProviderRule = {
  id: "corp",
  domains: ["mycompany.com", "mycompany.co"],
  canonicalDomain: "mycompany.com", // collapse the alias
  lowercaseLocal: true,
  removeDots: true,
  subaddressSeparators: ["+"],
};

normalizeEmail("John.Doe+x@mycompany.co", { providers: [corporate] });
// "johndoe@mycompany.com"
```

### 覆盖内置提供者

一个列出一个已存在的域名的用户提供者获胜,让你改变每个域的行为:

```ts
// Treat gmail.com strictly: keep dots, don't collapse googlemail, just lowercase.
normalizeEmail("John.Doe@gmail.com", {
  providers: [{ id: "gmail-strict", domains: ["gmail.com"], lowercaseLocal: true }],
});
// "john.doe@gmail.com"
```

### 替换所有提供者

完全忽略内置, 只使用自己的:

```ts
normalizeEmail("a@gmail.com", {
  replaceDefaultProviders: true,
  providers: [{ id: "only", domains: ["only.com"], subaddressSeparators: ["+"] }],
});
// gmail.com now matches nothing -> conservative default
```

### 每个域的默认规则

将规则应用到不匹配提供者的域中, 例如条 `+tags` 各地:

```ts
normalizeEmail("john+tag@example.com", {
  defaultRule: { lowercaseLocal: true, subaddressSeparators: ["+"] },
});
// "john@example.com"
```

A 类 `defaultRule` 从未覆盖匹配的提供者( Yahoo 仍然使用) `-`(见a/c.5/49/70,附件).

### 选项参考

```ts
interface NormalizeOptions {
  providers?: ProviderRule[];        // extra/override rules (win by domain)
  replaceDefaultProviders?: boolean; // ignore the built-ins entirely (default: false)
  defaultRule?: DefaultRule;         // rule for unmatched domains
  lowercaseDomain?: boolean;         // default: true
}

interface ProviderRule {
  id: string;                        // stable identifier, e.g. "gmail"
  domains: string[];                 // domains this rule applies to (case-insensitive)
  canonicalDomain?: string;          // collapse all matched domains to this one
  lowercaseLocal?: boolean;          // lowercase the local part
  removeDots?: boolean;              // strip dots from the local part (Gmail)
  subaddressSeparators?: string[];   // tag separators, e.g. ["+"] or ["-"]
}

// DefaultRule is a ProviderRule without `id`, `domains`, or `canonicalDomain`.
```

## 食谱

**复制地址列表**

```ts
import { normalizeEmail } from "@grml/nomadic";

const unique = [...new Map(
  rawEmails.map((e) => [normalizeEmail(e), e]),
).values()];
```

**以别名地址进行区块再登记**

```ts
import { isSameEmail } from "@grml/nomadic";

const alreadyUsed = existingUsers.some((u) => isSameEmail(u.email, signup.email));
```

**与原始键一起存储一个条形键**

```ts
const { normalized, valid } = normalizeEmailDetailed(input);
if (!valid) throw new Error("Invalid email");
await db.users.insert({ email: input, emailKey: normalized });
```

## 边缘案件和保障

-   地址是分拆的 **最后一个** `@`。 。 。 .
-   **引用** 当地部分(`"a..b"@x.com`)是逐字保存的,没有点/塔格变换.
-   索引 0 的分隔符(`+tag@gmail.com`)为 **忽略**; 剥去会清空本地部分 .
-   只有 **第一个** 分隔符作为切点( q)`a+b+c` 变成 `a`) (中文(简体) ).
-   域默认小写; 匹配的提供者 `canonicalDomain` (如果有的话)获胜.
-   非字符串输入抛出 `TypeError`。格式错误的输入返回时未改变 `valid: false`。 。 。 .

## 限制

-   `valid` 是一种轻量级综合检查, **没有** 完全RFC 5322验证或MX验证.
-   提供商规则反映了写作时有广泛记载的行为;提供商可以改变. 一切都是压倒一切的选择.
-   快信风格 **子域地址** (单位:千美元)`tag@user.fastmail.com`)没有解决,因为它取决于账户的域布局.

## 发展

```bash
npm install      # install dependencies
npm run build    # compile TypeScript to dist/ (tsc)
npm test         # build output is run as node scripts (dist/tests/*.js)
```

测试在 `tests/` 作为独立的脚本并运行在已编译的输出上。 CI (中文(简体) )`.github/workflows/ci.yml`在所有推/推上建立和运行它们.

## 许可证

公务员制度委员会

## 常见问题

### @grml/nomadic 是什么？

无害环境管理电子邮件正常化和与供应商认识规则\(Gmail、Outlook、Yahoo、iCloud等\)和完全自定义的供应商配置相适应\.注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

### 如何安装 @grml/nomadic？

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

### @grml/nomadic 支持 TypeScript 吗？

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

### @grml/nomadic 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @grml/nomadic 可以商用吗？

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

### @grml/nomadic 的下载量有多少？

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

### @grml/nomadic 还在维护吗？

最新版本 0\.1\.1 发布于 2026/06/04（5 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/06/04。作者已将其标记为弃用，新项目建议寻找替代方案。

