# @extractus/article-extractor 中文文档

规范地址：https://npmcn.com/package/%40extractus/article-extractor/

版本：9\.0\.1
npm 元数据更新时间：2026-08-20T09:57:26.832Z
中文译文更新时间：2026-11-14T06:14:13.837Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：171 kB，117 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2022-11-29T06:19:44.409Z
- 最新版本发布：2026-08-20T09:57:26.101Z
- 近 30 天下载量：145327（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 3 个）

## 中文简介

从给定的 URL 提取主要文章

## 安装

```sh
npm install @extractus/article-extractor
```

也可以使用：`pnpm add @extractus/article-extractor`、`yarn add @extractus/article-extractor`、`bun add @extractus/article-extractor`

## README

# @ extractus/ article- extractor

从 URL 中提取主文章,主图像和元数据 .

[![JSR](https://jsr.io/badges/@extractus/article-extractor)](https://jsr.io/@extractus/article-extractor) [![npm version](https://badge.fury.io/js/@extractus%2Farticle-extractor.svg)](https://badge.fury.io/js/@extractus%2Farticle-extractor) ![CI test](https://github.com/extractus/article-extractor/workflows/ci-test/badge.svg)

## 安装

### 德诺

```bash
deno add jsr:@extractus/article-extractor
```

### 节点.js / Bun

```bash
pnpm add jsr:@extractus/article-extractor
# or
npx jsr add @extractus/article-extractor
# or
bunx jsr add @extractus/article-extractor
```

或者从 npm 安装 :

```bash
npm install @extractus/article-extractor
# or
bun add @extractus/article-extractor
```

## 使用量

```ts
import { extract } from "jsr:@extractus/article-extractor";

const data = await extract("https://example.com/article");
console.log(data);
```

## APIs 密码

-   [`extract()`](https://npmcn.com/package/%40extractus/article-extractor/#readme-extract)
-   [`extractFromHtml()`](https://npmcn.com/package/%40extractus/article-extractor/#readme-extractfromhtml)
-   [转换](https://npmcn.com/package/%40extractus/article-extractor/#readme-transformations)
    -   [`Transformation` 对象](https://npmcn.com/package/%40extractus/article-extractor/#readme-transformation-object)
    -   [`addTransformations()`](https://npmcn.com/package/%40extractus/article-extractor/#readme-addtransformationstransformation--transformation)
    -   [`removeTransformations()`](https://npmcn.com/package/%40extractus/article-extractor/#readme-removetransformationspatterns-regexp)
    -   [优先权顺序](https://npmcn.com/package/%40extractus/article-extractor/#readme-priority-order)
-   [内容消毒选项](https://npmcn.com/package/%40extractus/article-extractor/#readme-content-sanitization-options)

* * *

### `extract()`

从 URL 或 HTML 字符串中装入并提取文章数据.

#### 语法

```ts
extract(input: string): Promise<ArticleData | null>
extract(input: string, parserOptions?: ParserOptions): Promise<ArticleData | null>
extract(input: string, parserOptions?: ParserOptions, fetcher?: Fetcher): Promise<ArticleData | null>
```

示例

```ts
import { extract } from "jsr:@extractus/article-extractor";

try {
  const article = await extract("https://example.com/some-article");
  console.log(article);
} catch (err) {
  console.error(err);
}
```

结果是 `null` (当找不到文章时)或 `ArticleData` 对象 :

```ts
interface ArticleData {
  url?: string;           // best resolved URL
  links?: string[];       // alternative URLs (canonical, shortlink, amphtml)
  title?: string;         // article title
  description?: string;   // short description / excerpt
  image?: string;         // main image URL
  favicon?: string;       // site favicon URL
  author?: string;        // author name
  content?: string;       // extracted article HTML
  source?: string;        // original publisher domain
  published?: string;     // publication date string
  ttr?: number;           // estimated time to read (seconds), 0 = unknown
  type?: string;          // page type (e.g. "article")
}
```

#### 参数

##### `input` _所需经费_

URL 字符串或原始 HTML 内容.

##### `parserOptions` _选项_

| 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `wordsPerMinute` | `number` | `300` | 每分钟读取时间估计的单词 |
| `descriptionTruncateLen` | `number` | `210` | 生成描述的最大字符 |
| `descriptionLengthThreshold` | `number` | `180` | 要保留元描述的最小字符 |
| `contentLengthThreshold` | `number` | `200` | 文章内容的最小字符 |
| `allowedTags` | `string[]` | _(语义/内容标记)_ | 要保持输出的 HTML 标记 |
| `allowedAttributes` | `Record<string, string[]>` | _(src, href, alt等)_ | 要保存的相加属性 |
| `allowedIframeDomains` | `string[]` | _(youtube, vimeo等_ | Iframe src 允许域 |

```ts
const article = await extract(url, {
  descriptionLengthThreshold: 120,
  contentLengthThreshold: 500,
});
```

##### `fetcher` _选项_

带有签名的自定义获取函数 `(url: string) => Promise<Response>`。 。 。 . 使用此功能来自定义 HTTP 行为: 代理,信头, TLS, 认证, 超时等.

默认为 `globalThis.fetch`。 。 。 .

**德诺** (带有代理) :

```ts
import { extract } from "@extractus/article-extractor";

const client = Deno.createHttpClient({
  proxy: { url: "http://proxy.example.com:8080" },
});
const myFetcher = (url: string) => fetch(url, { client });

const result = await extract("https://example.com/some-article", {}, myFetcher);
```

**节点.js** (通过undici使用代理) :

```ts
import { extract } from "@extractus/article-extractor";
import { fetch, ProxyAgent } from "undici";

const dispatcher = new ProxyAgent("http://proxy.example.com:8080");
const myFetcher = (url: string) => fetch(url, { dispatcher });

const result = await extract("https://example.com/some-article", {}, myFetcher);
```

**阿宝** (带有代理) :

```ts
import { extract } from "@extractus/article-extractor";

const myFetcher = (url: string) =>
  fetch(url, {
    proxy: "http://proxy.example.com:8080",
  });

const result = await extract("https://example.com/some-article", {}, myFetcher);
```

**自定义信头**数字 :

```ts
const myFetcher = (url: string) =>
  fetch(url, {
    headers: {
      "user-agent": "MyBot/1.0",
      authorization: "Bearer token123",
    },
  });

const result = await extract("https://example.com/some-article", {}, myFetcher);
```

**请求超时**数字 :

```ts
const myFetcher = (url: string) =>
  fetch(url, {
    signal: AbortSignal.timeout(5000),
  });

const result = await extract("https://example.com/some-article", {}, myFetcher);
```

* * *

### `extractFromHtml()`

从 HTML 字符串直接提取文章数据 .

#### 语法

```ts
extractFromHtml(html: string): Promise<ArticleData | null>
extractFromHtml(html: string, url?: string): Promise<ArticleData | null>
extractFromHtml(html: string, url?: string, parserOptions?: ParserOptions): Promise<ArticleData | null>
```

示例

```ts
import { extractFromHtml } from "jsr:@extractus/article-extractor";

const res = await fetch(url);
const html = await res.text();

const article = await extractFromHtml(html, url);
```

#### 参数

##### `html` _所需经费_

包含文章的 HTML 字符串 .

##### `url` _选项_

用于解析相对链接的源 URL.

##### `parserOptions` _选项_

见 [解析选项](https://npmcn.com/package/%40extractus/article-extractor/#readme-parseroptions-optional) 见上文.

* * *

### 转换

有时默认提取算法可能效果不佳. 变换让您每个站点加入前/后处理.

-   `addTransformations(transformation: Transformation | Transformation[]): number`
-   `removeTransformations(patterns?: RegExp[]): number`

#### `Transformation` 对象

```ts
interface Transformation {
  patterns: RegExp[];                        // URL patterns to match
  pre?: (document: Document) => Document;    // pre-process raw HTML
  post?: (document: Document) => Document;   // post-process extracted article
}
```

> 对于匹配的 URL `patterns`运行 `pre` ,取出文章,然后运行 `post` 在结果.

![extraction process](https://res.cloudinary.com/pwshub/image/upload/v1657336822/documentation/article-parser_extraction_process.png)

示例

```ts
import { addTransformations } from "jsr:@extractus/article-extractor";

addTransformations({
  patterns: [/([\w]+.)?domain\.tld\/*/],
  pre: (document) => {
    document.querySelectorAll(".advertise-area").forEach((el) => {
      el.parentNode?.removeChild(el);
    });
    return document;
  },
  post: (document) => {
    document.querySelectorAll("h4").forEach((el) => {
      const h2 = document.createElement("h2");
      h2.innerHTML = el.innerHTML;
      el.parentNode?.replaceChild(h2, el);
    });
    return document;
  },
});
```

要写更好的转换,请参考 [链接](https://github.com/WebReflection/linkedom) 编辑 [API 文档](https://developer.mozilla.org/en-US/docs/Web/API/Document)。 。 。 .

#### `addTransformations(transformation | Transformation[])`

添加单个或多个变换. 无转换 `patterns` 被忽略.

```ts
import { addTransformations } from "jsr:@extractus/article-extractor";

addTransformations([
  {
    patterns: [/([\w]+.)?abc\.tld\/*/],
    pre: (doc) => { /* ... */ return doc; },
    post: (doc) => { /* ... */ return doc; },
  },
  {
    patterns: [/([\w]+.)?xyz\.tld\/*/],
    post: (doc) => { /* ... */ return doc; },
  },
]);
```

#### `removeTransformations(patterns?: RegExp[])`

删除匹配给定模式的转换 。 调用无参数删除全部 .

```ts
import { removeTransformations } from "jsr:@extractus/article-extractor";

removeTransformations([
  /([\w]+.)?abc\.tld\/*/,
  /([\w]+.)?xyz\.tld\/*/,
]);
```

#### 优先权顺序

当多个转换相匹配时,它们都按顺序执行.

鉴于两个匹配的转换 `goo.gl`数字 :

```
pre_one -> pre_three -> extraction -> post_two -> post_four
```

* * *

### 内容消毒选项

取出HTML使用内置的DOM树行走器进行消毒. 被丢弃的标签被取出(没有被丢弃),被丢弃的属性被取出. 通过 `parserOptions`数字 :

```ts
import { extract } from "jsr:@extractus/article-extractor";

// allow class attributes on <code> and <div>
const article = await extract(url, {
  allowedAttributes: {
    a: ["href", "target", "title"],
    img: ["src", "srcset", "alt", "title"],
    code: ["class"],
    div: ["class"],
  },
});
```

查看全部默认值,参见 [`src/config.ts`](https://npmcn.com/package/%40extractus/article-extractor/src/config.ts)。 。 。 .

* * *

## 发展

```bash
git clone https://github.com/extractus/article-extractor.git
cd article-extractor

# run tests
deno test --allow-all

# lint
deno lint

# build npm package
deno run -A ./scripts/build_npm.ts
```

## 许可证

《麻省理工学院许可证》

## 支持项目

这个项目是我空余时间维持的 如果你认为这有帮助, 有一些简单的方式支持它的持续发展:

-   来帮助更多的人发现它.
-   给我买杯咖啡: [https://paypal.me/ndaidong (英语)](https://paypal.me/ndaidong)
-   订阅 [第 二 条 提取服务](https://rapidapi.com/pwshub-pwshub-default/api/article-extractor2) 在快速API上.

每一点支持都有助于保持该项目的积极维持。 谢谢

* * *

## 常见问题

### @extractus/article-extractor 是什么？

从给定的 URL 提取主要文章

### 如何安装 @extractus/article-extractor？

在项目目录运行 npm install @extractus/article-extractor，或使用 pnpm add / yarn add / bun add。

### @extractus/article-extractor 支持 TypeScript 吗？

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

### @extractus/article-extractor 支持 ESM 还是 CommonJS？

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

### @extractus/article-extractor 可以商用吗？

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

### @extractus/article-extractor 的下载量有多少？

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

### @extractus/article-extractor 还在维护吗？

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