# @email-lint/core 中文文档

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

版本：0\.3\.0
npm 元数据更新时间：2026-09-09T18:06:08.002Z
中文译文更新时间：2026-11-13T14:29:45.925Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：270 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：4 个
- 首次发布：2026-04-13T18:37:40.565Z
- 最新版本发布：2026-09-09T18:06:07.730Z
- 近 30 天下载量：98898（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Lint 电子邮件 HTML 用于客户端使用caniemail数据兼容. CLI + 库.

## 安装

```sh
npm install @email-lint/core
```

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

## README

# 电子邮件lint

用于客户端兼容的 Lint 电子邮件 HTML 。 校验 CSS 属性、 HTML 元素和属性 [邮件](https://www.caniemail.com/) 30+电子邮件客户端的数据.

```
$ email-lint check welcome.html

welcome.html
  12:5   error    cursor not supported (4/4 variants)  [gmail]
  18:3   warning  background-image not supported (2/6 variants: windows, windows-mail)  [outlook]
  24:10  warning  <picture> not supported (4/4 variants)  [gmail]

✖ 1 error, 2 warnings
```

## 为什么不直接用罐头?

你可以,而且你经常应该. `caniemail` 解析您的 HTML 和 CSS, 返回拆分出的问题 `errors` 财务报告和审定财务报表 `warnings`,和船舶 `groupIssues()` 财务报告和审定财务报表 `formatIssue()` 帮助你介绍他们。 这是一个很好的图书馆, 电子邮件林特建在它上.

它不做的是决定什么 在你的密码库, 或者在你面前的答案 在CI。 这就是燃灯的目的:

-   **家庭崩溃** ——"在gmail.android,gmail.ios,gmail.desktop-webmail,gmail.mobile-webmail中不支持"成为一行: `cursor not supported (4/4 variants) [gmail]`
-   **严重性规则** ——并非所有问题都是平等的. `cursor` 在电子邮件中是化妆品(降级为 `info`) (中文(简体) ). Gmail部队 `target="_blank"` 在所有链接上,所以如果你已经使用它,这就是 `info` 没有 `error`
-   **框架过滤** —— React Email 添加了预览文本块,预装图像标记,以及 `target="_blank"` 用于输出。 罐头信封上这些 电子邮件林特知道它们是框架文物 压制它们
-   **CLI 有退出代码** —— 说 `email-lint check` 在错误中退出1个,当唯一的发现是警告时退出0个,所以CI屏蔽了那些断断续续的东西,对其余的保持安静
-   **输出格式** – 漂亮的终端输出, 用于工具的 JSON, GitHub 动作说明, 在 PR diffs 上显示内含
-   **TSX 支持** - 指着一个 `.tsx` 它使+ lints 一步,不需要建造管道

## 安装

```sh
npm install @email-lint/core
```

## 国 际

```sh
# Lint HTML files
email-lint check emails/*.html

# Lint React Email components directly (.tsx/.jsx)
email-lint check src/emails/welcome.tsx

# Target specific clients
email-lint check welcome.html --preset gmail
email-lint check welcome.html --preset outlook

# Several at once, for the union of their clients
email-lint check welcome.html --preset gmail,outlook

# Drop clients your audience never uses
email-lint check welcome.html --exclude orange,mail-ru
email-lint check welcome.html --preset all-clients --exclude '*.android'

# Output formats
email-lint check welcome.html --format pretty   # default, colored terminal output
email-lint check welcome.html --format json      # structured JSON for tooling
email-lint check welcome.html --format github    # GitHub Actions annotations

# Expand collapsed diagnostics to one line per variant
email-lint check welcome.html --verbose
```

有代码的退出 `1` 当发现错误时, 把它放进CI中, 它只是工作.

### 预设

| 预设 | 客户 |
| --- | --- |
| `all-clients` | 全部30+客户端( 默认) |
| `gmail` | Gmail 桌面、 iOS、 Android、 移动网络 |
| `outlook` | 展望桌面、网络、窗口邮件 |
| `apple-mail` | 苹果邮件macOS, iOS |
| `yahoo` | Yahoo 邮件桌面、 iOS、 Android |

### 反应电子邮件 / TSX

当你通过 `.tsx` 或者说 `.jsx` 文件, CLI 自动 :

1.  使用 [吉地语](https://github.com/unjs/jiti) (不需要建设步骤)
2.  通过 HTML 将其渲染到 HTML `@react-email/components`
3.  启用框架感知过滤以压制已知的假阳性

导出您的组件为默认和可选导出 `testData` 用于道具:

```tsx
export const testData = { name: 'Jane' };

export default function Welcome({ name }: { name: string }) {
  return (
    <Html>
      <Body>
        <Text>Hey {name}</Text>
      </Body>
    </Html>
  );
}
```

```sh
email-lint check src/emails/welcome.tsx
```

使用 `--no-ignore-framework` 以禁用框架过滤,或 `--show-ignored` 在一个单独的章节中看到被压制的诊断.

## 图书馆 API

```ts
import { lint } from '@email-lint/core';

const html = '<div style="cursor: pointer;">Click</div>';
const result = lint(html, { preset: 'gmail' });

console.log(result.success);      // false
console.log(result.errorCount);   // 1
console.log(result.diagnostics);  // LintDiagnostic[]
```

### `lint(html, config?)`

回返a `LintResult` 根据客户家庭分类的诊断.

```ts
interface LintResult {
  diagnostics: LintDiagnostic[];
  errorCount: number;
  warningCount: number;
  success: boolean;
}

interface LintDiagnostic {
  severity: 'error' | 'warning' | 'info';
  title: string;                    // Feature name from caniemail
  message: string;                  // Human-readable message with notes
  family: string;                   // "gmail", "outlook", etc.
  variants: string[];               // Affected variants within the family
  familySize: number;               // Total variants in this family
  position?: {
    start: { line: number; column: number };
    end: { line: number; column: number };
  };
}

interface LintConfig {
  preset?: string;                  // Client preset (default: "all-clients")
  exclude?: string;                 // Clients to drop, comma-separated globs
  framework?: 'react-email';       // Enable framework-aware filtering
  showIgnored?: boolean;            // Keep suppressed diagnostics in output
}
```

### 格式化器

```ts
import { lint, formatPretty, formatJson, formatGitHub } from '@email-lint/core';

const result = lint(html);
console.log(formatPretty([result]));
console.log(formatJson([result]));
console.log(formatGitHub([result]));
```

## 如何运作

1.  **解析** - 将您的 HTML 提供给 [邮件](https://www.npmjs.com/package/caniemail),用于对照其兼容性数据库检查每个 CSS 属性、 HTML 元素和属性
2.  **严重性规则** ——适用上下文意识规则. `cursor` 在电子邮件中是化妆品,所以降级到 `info`. Gmail 部队 `target="_blank"` 在所有链接上,所以如果你已经使用它,这就是 `info` 还有
3.  **家庭崩溃** ——将每个变量的诊断组分入家庭. 代替4个单独的"Gmail Android / Gmail iOS / Gmail 桌面 / Gmail 移动"条目,你得到一个诊断显示 `(4/4 variants)`
4.  **框架过滤** ——在闪接回电子邮件组件时,压制由框架本身引起的诊断(审查文本块,预装图像标记,强制) `target="_blank"`(中文(简体) )

## GitHub 动作

```yaml
- name: Lint emails
  run: email-lint check 'src/emails/**/*.tsx' --format github
```

这个 `github` 用于物质释放 [工作流程命令](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions) 在您的 PR diffs 上显示内含注释 .

## 许可证

麻省理工学院

## 常见问题

### @email-lint/core 是什么？

Lint 电子邮件 HTML 用于客户端使用caniemail数据兼容\. CLI \+ 库\.

### 如何安装 @email-lint/core？

在项目目录运行 npm install @email-lint/core，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 email-lint，可以用 npx email-lint 直接运行。

### @email-lint/core 支持 TypeScript 吗？

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

### @email-lint/core 支持 ESM 还是 CommonJS？

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

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

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

### @email-lint/core 可以商用吗？

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

### @email-lint/core 的下载量有多少？

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

### @email-lint/core 还在维护吗？

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