# @devmehq/email-validator-js 中文文档

规范地址：https://npmcn.com/package/%40devmehq/email-validator-js/

版本：2\.10\.4
npm 元数据更新时间：2025-11-19T17:55:30.418Z
中文译文更新时间：2026-11-12T03:39:46.282Z
软件包许可：BSL 1\.1

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

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

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

- 包体积（解压后）：57.2 MB，46 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 12\.0
- 运行依赖：3 个
- 首次发布：2021-12-23T14:30:55.610Z
- 最新版本发布：2025-11-19T17:55:30.216Z
- 近 30 天下载量：80330（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：320（近 12 个月 5 个）

## 中文简介

MX记录的高级电子邮件验证,SMTP验证,一次性电子邮件检测,分批处理和缓存. 生产准备与TypeScript支持.

## 安装

```sh
npm install @devmehq/email-validator-js
```

也可以使用：`pnpm add @devmehq/email-validator-js`、`yarn add @devmehq/email-validator-js`、`bun add @devmehq/email-validator-js`

## README

# 高级电子邮件验证器

[![NPM version](https://badgen.net/npm/v/@devmehq/email-validator-js)](https://npm.im/@devmehq/email-validator-js) [![Build Status](https://github.com/devmehq/email-validator-js/workflows/CI/badge.svg)](https://github.com/devmehq/email-validator-js/actions) [![Downloads](https://img.shields.io/npm/dm/@devmehq/email-validator-js.svg)](https://www.npmjs.com/package/@devmehq/email-validator-js) [![UNPKG](https://img.shields.io/badge/UNPKG-OK-179BD7.svg)](https://unpkg.com/browse/@devmehq/email-validator-js@latest/) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/license-BSL%201.1-blue.svg)](https://npmcn.com/package/%40devmehq/email-validator-js/LICENSE.md)

🚀 **高级电子邮件验证库** 用于节点.js **MX 记录检查**, (中文(简体) ), **SMTP 核查**, (中文(简体) ), **一次性电子邮件检测**,以及 **还要多得多**现在使用 **批处理**, (中文(简体) ), **高级缓存**,以及 **详细错误报告**。 。 。 .

## 目录

-   [特征](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-features)
-   [使用大小写](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-use-cases)
-   [API / 云服务](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-api--cloud-hosted-service)
-   [许可证](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-license)
-   [安装](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-installation)
-   [快速启动](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-quick-start)
-   [API 参考](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-api-reference)
-   [配置](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-configuration-options)
-   [实例](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-examples)
-   [性能缓存( C)](https://npmcn.com/package/%40devmehq/email-validator-js/#readme--performance--caching)
-   [电子邮件提供者数据库](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-%EF%B8%8F-email-provider-databases)
-   [测试](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-testing)
-   [捐款](https://npmcn.com/package/%40devmehq/email-validator-js/#readme-contributing)

## 特征

QQ 检查电子邮件地址有效性

QQ 检查域名 TLD 列表中的电子邮件地址域有效性

QQ 检查电子邮件地址 MX 记录

QQ 检查电子邮件地址 SMTP 连接

请检查access-date=中的日期值 (帮助)

QQ 检查电子邮件地址免费电子邮件提供者状态

✅ **新来的:** 用货币控制批次电子邮件校验

✅ **新来的:** 带有错误代码的详细核查结果

✅ **新来的:** 为改进性能而建造的缓存

✅ **新来的:** 临时故障的自动重试机制

✅ **新来的:** RFC 5321 符合规定的验证

✅ **新来的:** 在综合名称支助下加强电子邮件地址的名称检测

✅ **新来的:** 带有缓存的域类型检测和建议

✅ **新来的:** 通过 WHOIS 查找获取域龄

✅ **新来的:** 通过 WHOIS 查询获取域注册状态

✅ **新来的:** 对AWS Lambda、Vercel Edge、Cloudflare Workers和更多的服务器支持

## 使用大小写

-   通过去除垃圾邮件来提高电子邮件活动的传送率
-   提高电子邮件打开率和您的IP营销声誉
-   保护网站免受垃圾邮件、垃圾邮件和假邮件之害
-   保护您的产品注册表免受假邮件的伤害
-   保护您的网站表格免受假邮件的伤害
-   用假邮件保护自己免受欺诈命令和账户的伤害
-   将电子邮件地址验证纳入您的网站表格
-   将电子邮件地址验证纳入您的后台管理和订单处理

## API / 云宿服务

我们提供这个 `email verification and validation and more advanced features` 在我们的可缩放云 API 服务提供 - 您可以尝试在这里 [电子邮件验证](https://email-check.app/products/email)

* * *

## 许可证

电子邮件验证员-js根据 [业务来源许可证1.1](https://npmcn.com/package/%40devmehq/email-validator-js/LICENSE.md)。 。 。 .

### 快速许可摘要

| 使用大小写 | 是否需要商业执照? |
| --- | --- |
| 为自己的研究、爱好和测试目的探索电子邮件验证程序 | **没有** |
| 使用电子邮件验证程序建立概念证明应用程序 | **没有** |
| 使用电子邮件验证程序建立创收应用程序 | **对** |
| 使用电子邮件验证器-js来构建作为服务提供的软件(SaaS) | **对** |
| 为任何制作目的伪造电子邮件验证器 | **对** |

📄 **商业许可证**访问 [电子邮件检查.app/许可证/电子邮件验证器](https://email-check.app/license/email-validator) 或者联系我们 [销售@ 电子邮件检查. app](mailto:sales@email-check.app?subject=Interested%20in%20email-validator-js%20commercial%20license)。 。 。 .

* * *

## 安装

通过 Yarn 安装模块 :

```bash
yarn add @devmehq/email-validator-js
```

或国家预防机制:

```bash
npm install @devmehq/email-validator-js
```

### 所需资源

-   节点.js-12.0
-   TypeScript QQ 4.0 (用于 TypeScript 用户)

### 构建系统

-   高效捆绑和打花树花的滚动用途
-   以单独的CJS和无害环境管理模块优化建筑产出
-   边缘环境的无服务器构建

## 快速启动

```typescript
import { verifyEmail } from '@devmehq/email-validator-js';

// Basic usage
const result = await verifyEmail({
  emailAddress: 'user@example.com',
  verifyMx: true,
  verifySmtp: true,
  timeout: 3000
});

console.log(result.validFormat); // true
console.log(result.validMx);     // true
console.log(result.validSmtp);   // true or false
```

## API 参考

### 核心职能

#### `verifyEmail(params: IVerifyEmailParams): Promise<IVerifyEmailResult>`

具有后向兼容性的基本电子邮件验证 .

**参数:**

-   `emailAddress` (字符串,需要):电子邮件地址以验证
-   `timeout` (数目):超时数以毫秒计(默认:4000)
-   `verifyMx` (boolean):检查MX记录(默认:虚假)
-   `verifySmtp` (boolean):验证 SMTP 连接( 默认: 假)
-   `smtpPort` (数目):自定义 SMTP 端口
-   `debug` (boolean):启用调试记录( 默认: 假)
-   `detectName` (boolean):从电子邮件地址检测姓名(默认:虚假)
-   `nameDetectionMethod` (功能):自定义名称检测方法
-   `suggestDomain` (boolean):启用域打字建议(默认:虚假)
-   `domainSuggestionMethod` (功能):自定义域建议方法
-   `commonDomains` (弦 \[ \] : 自定义推荐域列表

**回返情况:**

```typescript
{
  validFormat: boolean;
  validMx: boolean | null;
  validSmtp: boolean | null;
  detectedName?: DetectedName | null;
  domainSuggestion?: DomainSuggestion | null;
}
```

#### `verifyEmailDetailed(params: IVerifyEmailParams): Promise<DetailedVerificationResult>`

具有详细结果和错误代码的高级验证.

**补充参数:**

-   `checkDisposable` (boolean): 检查可支配邮件( 默认: 真)
-   `checkFree` (boolean):检查免费电子邮件提供者( 默认: 真)
-   `retryAttempts` (数目):对失败的尝试重试(默认:1)
-   `detectName` (boolean):从电子邮件地址检测姓名(默认:虚假)
-   `suggestDomain` (boolean):启用域打字建议(默认:在详细模式下为真)

**回返情况:**

```typescript
{
  valid: boolean;
  email: string;
  format: {
    valid: boolean;
    error?: VerificationErrorCode;
  };
  domain: {
    valid: boolean | null;
    mxRecords?: string[];
    error?: VerificationErrorCode;
  };
  smtp: {
    valid: boolean | null;
    error?: VerificationErrorCode;
  };
  disposable: boolean;
  freeProvider: boolean;
  detectedName?: DetectedName | null;
  domainSuggestion?: DomainSuggestion | null;
  metadata?: {
    verificationTime: number;
    cached: boolean;
  };
}
```

#### `verifyEmailBatch(params: IBatchVerifyParams): Promise<BatchVerificationResult>`

验证多个邮件与货币控制并行 .

**参数:**

-   `emailAddresses` (字符串 \[\], 需要): 用于验证的邮件组
-   `concurrency` (数目):并行处理限制(默认:5)
-   `detailed` (boolean):返回详细结果(默认:虚假)
-   `detectName` (boolean):从电子邮件地址检测姓名
-   `suggestDomain` (boolean):启用域打字建议
-   其他参数来自 `verifyEmail`

**回返情况:**

```typescript
{
  results: Map<string, DetailedVerificationResult | IVerifyEmailResult>;
  summary: {
    total: number;
    valid: number;
    invalid: number;
    errors: number;
    processingTime: number;
  };
}
```

### 名称检测函数

#### `detectName(email: string): DetectedName | null`

从电子邮件地址检测出第一个和最后一个名字 .

```typescript
const name = detectName('john.doe@example.com');
// Returns: { firstName: 'John', lastName: 'Doe', confidence: 0.9 }
```

**检测模式 :**

-   点分隔符 : `john.doe` - John Doe(90%的信心)
-   强调: `jane_smith` - 简·史密斯(80%的信心)
-   连字符 : `mary-johnson` 玛丽·约翰逊(80%的信心)
-   骆驼场: `johnDoe` - 约翰·多伊(70%的信心)
-   **复合名称**数字 : `mo1.test2` — Mo1 测试2(60%的置信度)
-   **混合数字**数字 : `user1.admin2` — 用户1 管理员2(60%的置信度)
-   **智能数字处理**数字 : `john.doe123` - 约翰·多伊(80%的信心)
-   **背景后缀**数字 : `john.doe.dev` - 约翰·多伊(70%的信心)
-   单名 : `alice` 爱丽丝(50%的信心)

**增强特性 :**

-   删除邮件别名( +后为文本)
-   对数字的智能处理(综合名称中的预留,去掉后缀)
-   确认背景后缀(dev、公司、销售、年份)
-   处理复杂的多部分名称
-   适当名称资本化
-   过滤常见的非名称前缀(admin,支持,信息等)

#### `detectNameFromEmail(params: IDetectNameParams): DetectedName | null`

有自定义方法支持的高级名称检测 .

```typescript
const customMethod = (email: string) => {
  // Your custom logic
  return { firstName: 'Custom', lastName: 'Name', confidence: 1.0 };
};

const name = detectNameFromEmail({
  email: 'user@example.com',
  customMethod: customMethod
});
```

**参数:**

-   `email` (字符串):电子邮件地址
-   `customMethod` (功能):自定义检测逻辑

#### `defaultNameDetectionMethod(email: string): DetectedName | null`

默认名称检测执行, 导出为自定义扩展 .

### 域建议函数

#### `suggestEmailDomain(email: string, commonDomains?: string[]): DomainSuggestion | null`

检测错误的电子邮件域并提出更正建议 .

```typescript
const suggestion = suggestEmailDomain('user@gmial.com');
// Returns: { original: 'user@gmial.com', suggested: 'user@gmail.com', confidence: 0.95 }

// With custom domain list
const customDomains = ['company.com', 'enterprise.org'];
const customSuggestion = suggestEmailDomain('user@compny.com', customDomains);
```

**特征 :**

-   70+ 默认常见的电子邮件域
-   字符串相似性算法
-   已知类型模式(95%的置信度)
-   基于域长的智能阈值
-   24小时缓存以进行表演

#### `suggestDomain(params: ISuggestDomainParams): DomainSuggestion | null`

有自定义方法支持的高级域建议.

```typescript
const suggestion = suggestDomain({
  domain: 'gmial.com',
  customMethod: myCustomMethod,
  commonDomains: ['company.com']
});
```

**参数:**

-   `domain` (字符串):要检查的领域
-   `customMethod` (功能):自定义建议逻辑
-   `commonDomains` (弦 \[ \] : 自定义域列表

#### `defaultDomainSuggestionMethod(domain: string, commonDomains?: string[]): DomainSuggestion | null`

默认域建议执行, 导出为自定义扩展 .

#### `isCommonDomain(domain: string, commonDomains?: string[]): boolean`

检查一个域是否在常见域列表中 .

```typescript
isCommonDomain('gmail.com'); // true
isCommonDomain('mycompany.com'); // false

// With custom list
isCommonDomain('mycompany.com', ['mycompany.com']); // true
```

#### `getDomainSimilarity(domain1: string, domain2: string): number`

计算两个域(0-1)之间的相似度分.

```typescript
getDomainSimilarity('gmail.com', 'gmial.com'); // 0.8
getDomainSimilarity('gmail.com', 'yahoo.com'); // 0.3
```

### WHOIS 职能

> **说明:** WHOIS功能使用PSL(公用后缀列表)验证,以确保域名有效性后再进行查询. 没有有效 TLD 的无效域或域将返回 `null`。 。 。 .

#### `getDomainAge(domain: string, timeout?: number): Promise<DomainAgeInfo | null>`

通过WHOIS查询获取域龄信息.

```typescript
const ageInfo = await getDomainAge('example.com');
// Returns:
// {
//   domain: 'example.com',
//   creationDate: Date,
//   ageInDays: 7890,
//   ageInYears: 21.6,
//   expirationDate: Date,
//   updatedDate: Date
// }

// Works with email addresses and URLs too
await getDomainAge('user@example.com');
await getDomainAge('https://example.com/path');
```

**参数:**

-   `domain` (字符串):要检查的领域、电子邮件或 URL
-   `timeout` (数量):超时数以毫秒计(默认:5000)

**回返情况:** `DomainAgeInfo` 对象或 `null` 如果搜索失败

#### `getDomainRegistrationStatus(domain: string, timeout?: number): Promise<DomainRegistrationInfo | null>`

通过WHOIS获取详细的域名注册状态.

```typescript
const status = await getDomainRegistrationStatus('example.com');
// Returns:
// {
//   domain: 'example.com',
//   isRegistered: true,
//   isAvailable: false,
//   status: ['clientTransferProhibited'],
//   registrar: 'Example Registrar',
//   nameServers: ['ns1.example.com', 'ns2.example.com'],
//   expirationDate: Date,
//   isExpired: false,
//   daysUntilExpiration: 365,
//   isPendingDelete: false,
//   isLocked: true
// }
```

**参数:**

-   `domain` (字符串):要检查的领域、电子邮件或 URL
-   `timeout` (数量):超时数以毫秒计(默认:5000)

**回返情况:** `DomainRegistrationInfo` 对象或 `null` 如果搜索失败

**特征 :**

-   支持50+TLD,配备WHOIS特定服务器
-   为未知 TLD 自动发现 WHOIS 服务器
-   分析WHOIS的各种响应格式
-   用于域名验证的 PSL( 公共后缀列表)
-   1小时结果缓存
-   从电子邮件和 URL 提取域

### 工具函数

#### `isDisposableEmail(emailOrDomain: string): boolean`

检查电子邮件是否使用一次性提供者 .

```typescript
isDisposableEmail('user@tempmail.com'); // true
isDisposableEmail('tempmail.com'); // true
isDisposableEmail('gmail.com'); // false
```

#### `isFreeEmail(emailOrDomain: string): boolean`

检查邮件是否使用免费提供者 .

```typescript
isFreeEmail('user@gmail.com'); // true
isFreeEmail('yahoo.com'); // true
isFreeEmail('corporate.com'); // false
```

#### `isValidEmail(emailAddress: string): boolean`

验证电子邮件格式(RFC 5321 兼容).

```typescript
isValidEmail('user@example.com'); // true
isValidEmail('invalid.email'); // false
```

**审定规则:**

-   正确@ 符号位置
-   本地部分最大 64 个字符
-   域最大253个字符
-   无连续点
-   无正反点
-   有效域 TLD

#### `isValidEmailDomain(emailOrDomain: string): boolean`

验证一个域是否有有效的 TLD .

```typescript
isValidEmailDomain('example.com'); // true
isValidEmailDomain('example.invalid'); // false
```

#### `clearAllCaches(): void`

清除所有内部缓存(包括域建议).

```typescript
clearAllCaches();
```

### 类型和接口

#### `DetectedName`

```typescript
interface DetectedName {
  firstName?: string;
  lastName?: string;
  confidence: number; // 0-1 scale
}
```

#### `DomainSuggestion`

```typescript
interface DomainSuggestion {
  original: string;
  suggested: string;
  confidence: number; // 0-1 scale
}
```

#### `NameDetectionMethod`

```typescript
type NameDetectionMethod = (email: string) => DetectedName | null;
```

#### `DomainSuggestionMethod`

```typescript
type DomainSuggestionMethod = (domain: string) => DomainSuggestion | null;
```

#### `DomainAgeInfo`

```typescript
interface DomainAgeInfo {
  domain: string;
  creationDate: Date;
  ageInDays: number;
  ageInYears: number;
  expirationDate: Date | null;
  updatedDate: Date | null;
}
```

#### `DomainRegistrationInfo`

```typescript
interface DomainRegistrationInfo {
  domain: string;
  isRegistered: boolean;
  isAvailable: boolean;
  status: string[];
  registrar: string | null;
  nameServers: string[];
  expirationDate: Date | null;
  isExpired: boolean;
  daysUntilExpiration: number | null;
  isPendingDelete?: boolean;
  isLocked?: boolean;
}
```

### 常数

#### `COMMON_EMAIL_DOMAINS`

用于打字检测的 70+ 常见电子邮件域的阵列 .

```typescript
import { COMMON_EMAIL_DOMAINS } from '@devmehq/email-validator-js';

console.log(COMMON_EMAIL_DOMAINS);
// ['gmail.com', 'yahoo.com', 'outlook.com', 'hotmail.com', ...]
```

**包括:**

-   大众免费提供者(Gmail、Yahoo、Outlook等)
-   商业电子邮件服务(Google Workspace,微软等)
-   注重隐私的提供者(ProtonMail、Tutanota等)
-   区域供应商(GMX、Yandex、QQ等)
-   托管服务(GoDaddy、Namecheap等)

### 错误代码

```typescript
enum VerificationErrorCode {
  INVALID_FORMAT = 'INVALID_FORMAT',
  INVALID_DOMAIN = 'INVALID_DOMAIN',
  NO_MX_RECORDS = 'NO_MX_RECORDS',
  SMTP_CONNECTION_FAILED = 'SMTP_CONNECTION_FAILED',
  SMTP_TIMEOUT = 'SMTP_TIMEOUT',
  MAILBOX_NOT_FOUND = 'MAILBOX_NOT_FOUND',
  MAILBOX_FULL = 'MAILBOX_FULL',
  NETWORK_ERROR = 'NETWORK_ERROR',
  DISPOSABLE_EMAIL = 'DISPOSABLE_EMAIL',
  FREE_EMAIL_PROVIDER = 'FREE_EMAIL_PROVIDER'
}
```

## 配置选项

### `timeout`

为 smtp 连接设置以毫秒计的超时 。 默认 : `4000`。 。 。 .

### `verifyMx`

启用或禁用域检查 。 这项工作分两步进行:

1.  验证域是否确实存在
2.  验证域有有效的 MX 记录

默认 : `false`。 。 。 .

### `verifySmtp`

启用或禁用邮箱检查 。 只有几台SMTP服务器允许这样做,即使如此,它是否有效取决于你对这些服务器的IP声誉. 这个图书馆进行最好的验证:

-   它回来了 `null` 对于 Yahoo 地址, 对于失败的连接, 对于未知的 SMTP 错误
-   它回来了 `true` 用于有效的 SMTP 响应
-   它回来了 `false` 用于针对地址的格式或信箱存在的 SMTP 错误

默认 : `false`。 。 。 .

### `checkDisposable` (NEW) (英语)

请检查access-date=中的日期值 (帮助) 电子邮件域名是否是已知的可支配电子邮件提供者 。 默认 : `false`。 。 。 .

### `checkFree` (NEW) (英语)

检查电子邮件域名是否是已知的自由电子邮件提供者 。 默认 : `false`。 。 。 .

### `detailed` (NEW) (英语)

返回带有错误代码的详细验证结果 。 默认 : `false`。 。 。 .

### `retryAttempts` (NEW) (英语)

对瞬态失败进行重试的次数 。 默认 : `1`。 。 。 .

## 实例

### 基本用途

```typescript
import { verifyEmail } from '@devmehq/email-validator-js';

const { validFormat, validSmtp, validMx } = await verifyEmail({ 
  emailAddress: 'foo@email.com', 
  verifyMx: true, 
  verifySmtp: true, 
  timeout: 3000 
});
// validFormat: true
// validMx: true
// validSmtp: true
```

### 详细核查(NEW)

```typescript
import { verifyEmailDetailed } from '@devmehq/email-validator-js';

const result = await verifyEmailDetailed({
  emailAddress: 'foo@email.com',
  verifyMx: true,
  verifySmtp: true,
  checkDisposable: true,
  checkFree: true
});
// result.valid: true
// result.disposable: false
// result.freeProvider: false
// result.domain.mxRecords: ['mx1.email.com', 'mx2.email.com']
// result.metadata.verificationTime: 125
```

### 批量验证( NEW)

```typescript
import { verifyEmailBatch } from '@devmehq/email-validator-js';

const emails = ['user1@gmail.com', 'user2@example.com', 'invalid@fake.com'];

const result = await verifyEmailBatch({
  emailAddresses: emails,
  concurrency: 5,
  verifyMx: true,
  detailed: true
});
// result.summary.valid: 2
// result.summary.invalid: 1
// result.summary.processingTime: 234
```

### 名称检测( ENHANCED)

```typescript
import { detectName, verifyEmailDetailed } from '@devmehq/email-validator-js';

// Standalone name detection - now with composite name support
const name = detectName('john.doe@example.com');
// name: { firstName: 'John', lastName: 'Doe', confidence: 0.9 }

// Handle alphanumeric composite names
const composite = detectName('mo1.test2@example.com');
// composite: { firstName: 'Mo1', lastName: 'Test2', confidence: 0.6 }

// Smart handling of numbers and suffixes
const withNumbers = detectName('john.doe123@example.com');
// withNumbers: { firstName: 'John', lastName: 'Doe', confidence: 0.8 }

const withSuffix = detectName('jane.smith.dev@example.com');
// withSuffix: { firstName: 'Jane', lastName: 'Smith', confidence: 0.7 }

// Integrated with email verification
const result = await verifyEmailDetailed({
  emailAddress: 'jane_smith@example.com',
  detectName: true
});
// result.detectedName: { firstName: 'Jane', lastName: 'Smith', confidence: 0.8 }

// Custom detection method
const customMethod = (email: string) => {
  // Your custom logic here
  return { firstName: 'Custom', lastName: 'Name', confidence: 1.0 };
};

const resultCustom = await verifyEmail({
  emailAddress: 'user@example.com',
  detectName: true,
  nameDetectionMethod: customMethod
});
```

### 域泰波探测器( NEW)

```typescript
import { suggestEmailDomain, verifyEmailDetailed } from '@devmehq/email-validator-js';

// Standalone domain suggestion
const suggestion = suggestEmailDomain('user@gmial.com');
// suggestion: { original: 'user@gmial.com', suggested: 'user@gmail.com', confidence: 0.95 }

// Integrated with email verification (enabled by default in detailed mode)
const result = await verifyEmailDetailed({
  emailAddress: 'john@yaho.com',
  suggestDomain: true  // Default: true for detailed verification
});
// result.domainSuggestion: { original: 'john@yaho.com', suggested: 'john@yahoo.com', confidence: 0.9 }

// With custom domain list
const customDomains = ['company.com', 'enterprise.org'];
const resultCustom = await verifyEmail({
  emailAddress: 'user@compny.com',
  suggestDomain: true,
  commonDomains: customDomains
});
// resultCustom.domainSuggestion: { suggested: 'user@company.com', confidence: 0.85 }
```

### 处理不同的验证情景

当一个域不存在或没有MX记录时:

```typescript
const result = await verifyEmail({ 
  emailAddress: 'foo@bad-domain.com', 
  verifyMx: true, 
  verifySmtp: true 
});
// validFormat: true
// validMx: false
// validSmtp: null (couldn't be performed)
```

### 使用详细核查来改进视野

```typescript
const detailed = await verifyEmailDetailed({
  emailAddress: 'user@suspicious-domain.com',
  verifyMx: true,
  verifySmtp: true,
  checkDisposable: true,
  checkFree: true
});

if (!detailed.valid) {
  switch (detailed.domain.error) {
    case VerificationErrorCode.DISPOSABLE_EMAIL:
      console.log('Rejected: Disposable email');
      break;
    case VerificationErrorCode.NO_MX_RECORDS:
      console.log('Rejected: Invalid domain');
      break;
    case VerificationErrorCode.MAILBOX_NOT_FOUND:
      console.log('Rejected: Mailbox does not exist');
      break;
  }
}
```

### 大列表批处理

```typescript
const emails = [
  'valid@gmail.com',
  'test@tempmail.com',
  'user@company.com',
  // ... hundreds more
];

const batch = await verifyEmailBatch({
  emailAddresses: emails,
  concurrency: 10, // Process 10 emails simultaneously
  verifyMx: true,
  checkDisposable: true,
  detailed: true
});

console.log(`Processed ${batch.summary.total} emails`);
console.log(`Valid: ${batch.summary.valid}`);
console.log(`Invalid: ${batch.summary.invalid}`);
console.log(`Time: ${batch.summary.processingTime}ms`);

// Filter out invalid emails
const validEmails = [];
for (const [email, result] of batch.results) {
  if (result.valid) {
    validEmails.push(email);
  }
}
```

### 用缓存优化性能

```typescript
// First verification - hits DNS and SMTP
const first = await verifyEmail({ 
  emailAddress: 'cached@example.com',
  verifyMx: true 
});
// Takes ~500ms

// Second verification - uses cache
const second = await verifyEmail({ 
  emailAddress: 'cached@example.com',
  verifyMx: true 
});
// Takes ~1ms (cached)

// Clear cache if needed
clearAllCaches();
```

**说明:** Yahoo, Hotmail, 和一些供应商总是回来 `validSmtp: true` 因为他们不允许检查信箱.

## 无服务器部署

该包包括主要云平台的无服务器适配器. 无服务器执行提供没有Node.js依赖的电子邮件验证,使其适合边缘计算环境.

### AWS 兰布达

```javascript
import { apiGatewayHandler } from '@devmehq/email-validator-js/serverless/aws';

export const handler = apiGatewayHandler;
```

### Vercel边缘函数

```javascript
import { edgeHandler } from '@devmehq/email-validator-js/serverless/vercel';

export const config = {
  runtime: 'edge',
};

export default edgeHandler;
```

### 云花岗工人

```javascript
import { workerHandler } from '@devmehq/email-validator-js/serverless/cloudflare';

export default {
  async fetch(request, env, ctx) {
    return workerHandler(request, env, ctx);
  },
};
```

### 无服务器模式的特性

-   语法验证
-   Typo 检测和域建议
-   \* \*\* 可处理的电子邮件检测(完整的数据库)
-   \* 免费电子邮件提供者检测(完整的数据库)
-   批量处理
-   内置缓存
-   MX记录验证( 需要 DNS)
-   SMTP 校验( 需要 TCP 套接字)

关于详细的无服务器文档和更多平台实例,参见 [文件/服务](https://npmcn.com/package/%40devmehq/email-validator-js/SERVERLESS.md)。 。 。 .

## 性能缓存( C)

图书馆包括智能缓存以提高性能:

| 缓存类型 | TTL 电话 | 说明 |
| --- | --- | --- |
| MX 记录 | 1小时 | DNS MX 记录查看 |
| 可处理 | 24小时 | 可处理的电子邮件检查 |
| 免费提供者 | 24小时 | 免费电子邮件提供者检查 |
| 域有效性 | 24小时 | 域验证结果 |
| SMTP 软件 | 30分钟 | SMTP 核查结果 |
| 域建议 | 24小时 | 域类型建议 |

### 性能提示

1.  **使用批处理**: 对于多个电子邮件,使用 `verifyEmailBatch()` 用于平行处理
2.  **启用缓存**: 缓存是自动的, 重复检查减少~90%
3.  **调整超时**: 较快反应的超时,准确性较高
4.  **跳过 SMTP**: 如果您只需要格式/ MX 验证, 请跳过 SMTP 以获得更快的结果
5.  **域建议**: 缓存24小时以避免重新计算相似性分数
6.  **名称检测**: 性能影响最小的轻量级操作

## 电子邮件提供者数据库

### 可处理的电子邮件提供者( QQ 总是更新)

[查看列表](https://npmcn.com/package/%40devmehq/email-validator-js/src/disposable-email-providers.json) - 5 000多个一次性电子邮件域

### 免费电子邮件提供者( QQ 总是更新)

[查看列表](https://npmcn.com/package/%40devmehq/email-validator-js/src/free-email-providers.json) - 1 000+免费电子邮件提供者

### 常见电子邮件域 (QQNEW)

访问用于打字检测的 70+ 常见电子邮件域列表 :

```typescript
import { COMMON_EMAIL_DOMAINS } from '@devmehq/email-validator-js';

console.log(COMMON_EMAIL_DOMAINS);
// ['gmail.com', 'yahoo.com', 'outlook.com', 'hotmail.com', ...]

// Use with your own domain validation
const isCommon = COMMON_EMAIL_DOMAINS.includes('gmail.com'); // true
```

## 测试

运行测试套件 :

```bash
yarn test
```

覆盖运行 :

```bash
yarn test --coverage
```

打开代码 :

```bash
yarn lint
yarn lint-fix  # Auto-fix issues
```

构建工程 :

```bash
yarn build
```

## 发展

### 项目结构

```
email-validator-js/
├── src/                 # Source code
│   ├── index.ts        # Main entry point
│   ├── smtp.ts         # SMTP verification
│   ├── dns.ts          # DNS/MX lookups
│   ├── validator.ts    # Format validation
│   ├── cache.ts        # Caching system
│   ├── batch.ts        # Batch processing
│   └── types.ts        # TypeScript types
├── __tests__/          # Test files
├── examples/           # Usage examples
└── dist/              # Compiled output
```

### 脚本

```bash
yarn build      # Build TypeScript with Rollup
yarn test       # Run tests with Jest
yarn lint       # Run ESLint
yarn lint-fix   # Fix ESLint issues
yarn typecheck  # Run TypeScript type checking
```

### 构建优化

-   **类型安全**: 改进型推论减少冗余型声明
-   **套装大小**: 以震树和微音优化
-   **业绩**: 加快与平行汇编的构建
-   **代码质量**: 有全面类型检查的严格类型脚本模式

## 捐款

我们欢迎捐款! 请随意打开一个问题或创建拉出请求并修正错误或添加特性. 欢迎所有的贡献!

### 如何贡献

1.  叉子存储器
2.  创建特性分支( E)`git checkout -b feature/amazing-feature`(中文(简体) )
3.  提交更改( E)`git commit -m 'Add amazing feature'`(中文(简体) )
4.  推向分行(`git push origin feature/amazing-feature`(中文(简体) )
5.  打开拉请求

### 开发设置

```bash
# Clone the repo
git clone https://github.com/devmehq/email-validator-js.git
cd email-validator-js

# Install dependencies
yarn install

# Run tests
yarn test

# Build
yarn build
```

## 支助

关于问题、问题或商业许可:

🐛 [打开一个问题](https://github.com/devmehq/email-validator-js/issues) 📧 [电子邮件支持](mailto:support@email-check.app) 📄 [商业许可证](https://email-check.app/license/email-validator) 🌐 [访问电子邮件检查. app](https://email-check.app/)

## 自由主义

业务来源许可证1.1 - 见 [自由主义](https://npmcn.com/package/%40devmehq/email-validator-js/LICENSE.md) 详细文件.

### 你什么时候需要商业执照?

BSL只允许用于非生产目的. 这是一份综合指南,帮助你理解 当你需要商业许可证:

| 使用大小写 | 需要商业执照吗? | 细节 |
| --- | --- | --- |
| **个人学习( L)** |  |  |
| 探索用于研究或学习的电子邮件验证器-js | ✅ **没有** | 为教育目的自由使用 |
| 个人爱好项目(非商业性) | ✅ **没有** | 建立个人工具和实验 |
| \* 开发环境中的测试和评价 | ✅ **没有** | 在购买前测试所有特性 |
| **开发和原型制作** |  |  |
| 建立概念证明应用程序 | ✅ **没有** | 创建演示和原型 |
| \* \* 内部工具(不是介绍客户) | ✅ **没有** | 内部开发工具的使用 |
| \* 开源项目(非商业性) | ✅ **没有** | 对社区的贡献 |
| **商业和生产用途** |  |  |
| 创收应用程序 | ❌ **对** | 任何能产生收入的应用程序 |
| 作为服务(SaaS)产品的软件 | ❌ **对** | 基于云的服务 |
| 分发的商业软件 | ❌ **对** | 出售给客户的软件 |
| 企业生产系统 | ❌ **对** | 业务关键应用程序 |
| 用于商业目的的伪造 | ❌ **对** | 创造衍生商品 |
| \* 任何形式的生产用途 | ❌ **对** | 服务于真实用户的直播系统 |
| **具体设想** |  |  |
| \* 学生项目和课程 | ✅ **没有** | 鼓励学术使用 |
| \* CI/CD管道(用于商业产品) | ❌ **对** | 商业发展的一部分 |
| 生产 API 中的电子邮件验证 | ❌ **对** | 生产服务使用情况 |
| 电子商务结账验证 | ❌ **对** | 与收入有关的审定 |
| QQ 移动应用程序(免费的广告或付费) | ❌ **对** | 货币化应用 |

### 快速决策指南

问自己这些问题:

1.  **真正的用户在制作中会与之互动吗?** 你需要执照
2.  **这有助于创造收入吗?** 你需要执照
3.  **这是学习还是测试?** • 不需要许可证
4.  **这是内部原型还是POC?** • 不需要许可证

### 为什么选择我们的商业执照?

✨ **无限使用** - 在所有生产应用中使用  
🚀 **优先支助** - 我们工程队的直接支助  
🔄 **常规更新** - 获得最新特点和改进  
🛡️ **法律保护** - 充分的商业权利和担保  
🏢 **企业准备** - 适用于大规模部署

### 获取您的商业执照

准备好在制作时使用电子邮件验证器了吗?

🛍️ **[购买许可证](https://email-check.app/license/email-validator)** - 简单定价,即时激活  
📧 **[联系人销售](mailto:sales@email-check.app?subject=Interested%20in%20email-validator-js%20commercial%20license)** - 企业或定制需求

## 常见问题

### @devmehq/email-validator-js 是什么？

MX记录的高级电子邮件验证,SMTP验证,一次性电子邮件检测,分批处理和缓存\. 生产准备与TypeScript支持\.

### 如何安装 @devmehq/email-validator-js？

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

### @devmehq/email-validator-js 支持 TypeScript 吗？

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

### @devmehq/email-validator-js 支持 ESM 还是 CommonJS？

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

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

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

### @devmehq/email-validator-js 可以商用吗？

@devmehq/email-validator-js 使用 BSL 1\.1 许可。声明的许可为 BSL 1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @devmehq/email-validator-js 的下载量有多少？

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

### @devmehq/email-validator-js 还在维护吗？

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