# @apidojo/x-scraper 中文文档

规范地址：https://npmcn.com/package/%40apidojo/x-scraper/

版本：1\.1\.0
npm 元数据更新时间：2026-03-14T08:52:22.746Z
中文译文更新时间：2026-11-06T10:12:54.913Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：141 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2026-03-14T08:52:22.179Z
- 最新版本发布：2026-03-14T08:52:22.398Z
- 近 30 天下载量：3887（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

以最快且最便宜的方式刮去X (Twitter)的微博. 以开发者友好的API包装了认证的Twitter Scraper Lite演员.

## 安装

```sh
npm install @apidojo/x-scraper
```

也可以使用：`pnpm add @apidojo/x-scraper`、`yarn add @apidojo/x-scraper`、`bun add @apidojo/x-scraper`

## README

# x- 扫描器

以最快且最便宜的方式刮去X (Twitter)的微博. 包括企业团队在内的数以万计的客户使用经过战斗测试的基础设施.

环绕 [认证 Twitter Scraper Lite](https://apify.com/apidojo/twitter-scraper-lite?fpr=yhdrb) 演员有开发者友好,以阶级为基础的API. 每一种方法都创造了一个在引擎盖下运行的辅助演员.

## 先决条件

-   **节点.js 16+**
-   一个 **说明已付款计划的账户** —— 说 [在这儿报名](https://apify.com/?fpr=yhdrb)
-   一个 **认证 API 令牌** —— 说 [拿过来](https://console.apify.com/account/integrations)

## 安装

```bash
npm install @apidojo/x-scraper
```

## CLI 使用量

从命令行安装到全球使用 :

```bash
npm install -g @apidojo/x-scraper
```

### 设置

```bash
# Store your Apify token (saved to ~/.x-scraper/config.json)
x-scraper init

# Or pass it per-command
x-scraper profile NASA --token apify_api_xxx

# Or set as environment variable
export APIFY_TOKEN=apify_api_xxx
```

### 图标

```bash
# Fetch tweets from a profile
x-scraper profile NASA --sort Latest --max-items 50

# Search by keyword
x-scraper keyword "artificial intelligence" --lang en --sort Latest

# Search by multiple keywords (joined with OR)
x-scraper keywords bitcoin ethereum solana

# Search by hashtag
x-scraper hashtag AI MachineLearning --sort Latest

# Fetch a single tweet by URL
x-scraper url https://x.com/elonmusk/status/1728108619189874825

# Fetch from multiple URLs
x-scraper urls https://x.com/a/status/1 https://x.com/b/status/2

# Tweets from a handle within a date range
x-scraper profile-date-range NASA --since 2024-01-01 --until 2024-06-01

# Tweets near a location
x-scraper location coffee --location "San Francisco" --radius 10mi

# Tweets with minimum engagement
x-scraper engagement bitcoin --min-likes 1000 --min-retweets 100

# Multiple profiles in one run
x-scraper profiles elonmusk naval paulg

# Mentions, media filters, cashtags, verified users, and more
x-scraper mention NASA
x-scraper media NASA
x-scraper images NASA
x-scraper videos NASA
x-scraper cashtag BTC ETH SOL
x-scraper verified cryptocurrency
x-scraper no-retweets elonmusk
x-scraper links TechCrunch
x-scraper conversation 1728108619189874825

# Raw actor input (full control)
x-scraper search --input '{"searchTerms":["from:NASA filter:media"]}'
x-scraper execute --input '{"searchTerms":["test"],"maxItems":10}'
```

### 输出选项

```bash
# Pretty JSON (default)
x-scraper profile NASA

# Compact JSON (pipe-friendly)
x-scraper profile NASA --json

# JSONL (one object per line)
x-scraper profile NASA --jsonl

# Save to file
x-scraper profile NASA --output tweets.json

# Debug mode (shows internal logs)
x-scraper profile NASA --debug
```

### 全球旗帜

| 旗帜 | 说明 |
| --- | --- |
| `--token <token>` | 认证 API 令牌( 覆盖内嵌/ 配置) |
| `--sort <order>` | `Latest`, (中文(简体) ), `Top`,或 `"Latest + Top"` |
| `--max-items <n>` | 最大项目数 |
| `--lang <code>` | 语言过滤器(ISO 639-1) |
| `--timeout <secs>` | 以秒计超时 |
| `--output <file>` | 将输出保存到文件 |
| `--json` | 压缩 JSON 输出 |
| `--jsonl` | JSONL 输出(每行1个JSON) |
| `--debug` | 启用调试模式 |

## 快速启动( 图书馆)

```javascript
// ESM
import { XScraper } from '@apidojo/x-scraper';

// CommonJS
const { XScraper } = require('@apidojo/x-scraper');

const scraper = new XScraper({ token: 'apify_api_xxxxxxxxxxxx' });

// Fetch latest tweets from NASA
const tweets = await scraper.getTweetsByProfile('NASA', { sort: 'Latest', maxItems: 50 });
console.log(tweets);
```

## 核心方法

### `execute(input, options?)`

Raw通过——直接传递任何有效的演员输入对象. 当你知道演员期望的输入时使用这个.

```javascript
const tweets = await scraper.execute({
  searchTerms: ['from:NASA filter:media'],
  sort: 'Latest',
  maxItems: 100,
});
```

### `search(input, options?)`

同步运行刮取器——等待运行完成并返回所有项目. 选项 `sort`, (中文(简体) ), `maxItems`,以及 `lang` 自动合并到输入中.

```javascript
const tweets = await scraper.search(
  { searchTerms: ['from:NASA'] },
  { sort: 'Latest', maxItems: 50, lang: 'en' }
);
```

### `searchAsync(input, options?)`

启动跑步而不等待。 回返a `RunHandle` 投票和获得结果。 用于超过同步超时的大型运行 .

```javascript
const run = await scraper.searchAsync(
  { searchTerms: ['from:NASA'] },
  { sort: 'Latest' }
);

await run.waitForFinish();
const tweets = await run.getItems();
```

### `stream(input, options?)`

运行刮取器和流结果 作为同步执行器。 物品逐一取出,并有自动涂层.

```javascript
for await (const tweet of scraper.stream({ searchTerms: ['from:NASA'] })) {
  console.log(tweet.text);
}
```

## 方便方法

所有方便方法都接受 `options` 对象 :

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `sort` | `string` | `'Latest'`, (中文(简体) ), `'Top'`,或 `'Latest + Top'` |
| `maxItems` | `number` | 返回的最大项数 |
| `lang` | `string` | ISO 639-1语言代码(例如. `'en'`(中文(简体) ) |
| `timeout` | `number` | 超时秒( 默认: 120) |
| `fullResponse` | `boolean` | 返回时 `{ items, runId, datasetId }` 而不是只是项目 |

### 简介

```javascript
// Tweets from a single profile
const tweets = await scraper.getTweetsByProfile('NASA', { sort: 'Latest' });

// Tweets from multiple profiles in one run
const tweets = await scraper.getTweetsByMultipleProfiles(
  ['elonmusk', 'naval', 'paulg'],
  { sort: 'Latest' }
);

// Tweets from a handle within a date range
const tweets = await scraper.getTweetsByHandleInDateRange(
  'NASA', '2024-01-01', '2024-06-01',
  { sort: 'Latest' }
);

// Exclude retweets from a handle
const tweets = await scraper.getTweetsExcludingRetweetsByHandle('elonmusk', {
  sort: 'Latest',
});
```

### 搜索

```javascript
// Search by keyword
const tweets = await scraper.getTweetsByKeyword('artificial intelligence', {
  lang: 'en',
  sort: 'Latest',
});

// searchTweets is an alias for getTweetsByKeyword
const tweets = await scraper.searchTweets('artificial intelligence');

// Search by multiple keywords (joined with OR)
const tweets = await scraper.getTweetsByKeywords(
  ['bitcoin', 'ethereum', 'solana'],
  { lang: 'en', sort: 'Latest' }
);

// searchTweetsByMultipleKeywords is an alias for getTweetsByKeywords
const tweets = await scraper.searchTweetsByMultipleKeywords(['AI', 'ML', 'deep learning']);

// Search by hashtag
const tweets = await scraper.getTweetsByHashtag(['AI', 'MachineLearning'], {
  sort: 'Latest',
});

// Search by cashtag
const tweets = await scraper.getTweetsByCashtag(['BTC', 'ETH', 'SOL'], {
  lang: 'en',
  sort: 'Latest',
});
```

### 单调和 URL

```javascript
// Fetch a single tweet by URL
const tweets = await scraper.getTweetByUrl(
  'https://x.com/elonmusk/status/1728108619189874825'
);

// Fetch from multiple URLs (tweets, lists, profiles)
const tweets = await scraper.getTweetsByUrls([
  'https://x.com/elonmusk/status/1728108619189874825',
  'https://twitter.com/i/lists/1234567890',
]);
```

### 对话

```javascript
// Fetch replies in a conversation thread
const replies = await scraper.getTweetsByConversationId('1728108619189874825', {
  sort: 'Latest',
});
```

### 提及

```javascript
// Tweets mentioning a user
const tweets = await scraper.getTweetsByMention('NASA', { sort: 'Latest' });
```

### 媒体过滤器

```javascript
// Tweets with any media (images or videos)
const tweets = await scraper.getTweetsWithMediaByHandle('NASA');

// Tweets with images only
const tweets = await scraper.getTweetsWithImagesByHandle('NASA');

// Tweets with videos only
const tweets = await scraper.getTweetsWithVideosByHandle('NASA');

// Tweets with links
const tweets = await scraper.getTweetsWithLinksByHandle('TechCrunch');
```

### 接触过滤器( F)

```javascript
// Tweets with minimum engagement
const tweets = await scraper.getTweetsWithMinEngagement('bitcoin', {
  minLikes: 1000,
  minRetweets: 100,
  sort: 'Top',
});

// Tweets from verified users only
const tweets = await scraper.getTweetsByVerifiedUsers('cryptocurrency', {
  sort: 'Top',
});
```

### 地点

```javascript
// Tweets near a location
const tweets = await scraper.getTweetsByLocation('coffee', 'San Francisco', '10mi', {
  sort: 'Latest',
});
```

## 完全响应模式

默认情况下,方法只返回项目数组。 过 `{ fullResponse: true }` 以获取运行的元数据 :

```javascript
const result = await scraper.getTweetsByProfile('NASA', {
  sort: 'Latest',
  fullResponse: true,
});

console.log(result.items);     // Array of tweet objects
console.log(result.runId);     // Apify run ID
console.log(result.datasetId); // Apify dataset ID
```

## 与 RunHandle 同步运行

对于需要超过同步超时的大型运行:

```javascript
const run = await scraper.searchAsync({ searchTerms: ['from:NASA'], sort: 'Latest' });

// Poll until the run finishes
await run.waitForFinish();

// Get all items
const tweets = await run.getItems();

// Or stream items
for await (const tweet of run.stream()) {
  console.log(tweet.text);
}

// Access run metadata
console.log(run.runId);
console.log(run.datasetId);
console.log(run.status);
```

## 处理错误

所有来自 Apify 的错误都直接抛出 。 盘点尝试/捕获的呼叫:

```javascript
try {
  const tweets = await scraper.getTweetsByProfile('NASA');
} catch (error) {
  // Apify errors: 401 unauthorized, 404 not found, 429 rate limit, run failures
  console.error('Scraper error:', error.message);
}
```

如果没有提供令牌,则构造者立即投出:

```javascript
try {
  const scraper = new XScraper({});
} catch (error) {
  // "APIFY_TOKEN is required. Pass it as: new XScraper({ token: "apify_api_xxx" })"
}
```

## 图文对象形状

每件退回的物品都是个微博对象:

```json
{
  "type": "tweet",
  "id": "1728108619189874825",
  "url": "https://x.com/elonmusk/status/1728108619189874825",
  "text": "More than 10 per human on average",
  "retweetCount": 11311,
  "replyCount": 6526,
  "likeCount": 104121,
  "quoteCount": 2915,
  "createdAt": "Fri Nov 24 17:49:36 +0000 2023",
  "lang": "en",
  "isReply": false,
  "isRetweet": false,
  "isQuote": true,
  "author": {
    "userName": "elonmusk",
    "name": "Elon Musk",
    "id": "44196397",
    "followers": 172669889,
    "isVerified": true,
    "isBlueVerified": true
  }
}
```

## API 参考

### 构造器

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `token` | `string` | _所需经费_ | 认证 API 令牌 |
| `timeout` | `number` | `120` | 同步运行的默认超时秒数 |

### 核心方法

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `execute(input, options?)` | `Promise<items|FullResponse>` | 原始输入传递 |
| `search(input, options?)` | `Promise<items|FullResponse>` | 与选项合并同步运行 |
| `searchAsync(input, options?)` | `Promise<RunHandle>` | Async 运行, 返回控件 |
| `stream(input, options?)` | `AsyncGenerator<tweet>` | 对项目的同步转发器 |

### 方便方法

| 方法 | 参数 | 构建查询 |
| --- | --- | --- |
| `getTweetsByProfile` | `(handle, opts?)` | `from:{handle}` |
| `getTweetsByHandleInDateRange` | `(handle, since, until, opts?)` | `from:{handle} since:... until:...` |
| `getTweetsByHashtag` | `(hashtags, opts?)` | `#tag1 #tag2` |
| `getTweetsByKeyword` | `(keyword, opts?)` | `{keyword}` |
| `searchTweets` | `(keyword, opts?)` | 别名 `getTweetsByKeyword` |
| `getTweetsByKeywords` | `(keywords[], opts?)` | `kw1 OR kw2 OR kw3` |
| `searchTweetsByMultipleKeywords` | `(keywords[], opts?)` | 别名 `getTweetsByKeywords` |
| `getTweetsByConversationId` | `(id, opts?)` | `conversation_id:{id}` |
| `getTweetByUrl` | `(url, opts?)` | `startUrls: [url]` |
| `getTweetsByUrls` | `(urls[], opts?)` | `startUrls: [...urls]` |
| `getTweetsByLocation` | `(query, location, radius, opts?)` | `{q} near:"{loc}" within:{r}` |
| `getTweetsByMultipleProfiles` | `(handles[], opts?)` | `["from:a","from:b"]` |
| `getTweetsByCashtag` | `(cashtags, opts?)` | `$X OR $Y` |
| `getTweetsByMention` | `(handle, opts?)` | `@{handle}` |
| `getTweetsWithMediaByHandle` | `(handle, opts?)` | `from:{handle} filter:media` |
| `getTweetsWithImagesByHandle` | `(handle, opts?)` | `from:{handle} filter:images` |
| `getTweetsWithVideosByHandle` | `(handle, opts?)` | `from:{handle} filter:videos` |
| `getTweetsWithMinEngagement` | `(query, opts?)` | `{q} min_faves:{n} min_retweets:{n}` |
| `getTweetsByVerifiedUsers` | `(query, opts?)` | `{q} filter:verified` |
| `getTweetsExcludingRetweetsByHandle` | `(handle, opts?)` | `from:{handle} -filter:retweets` |
| `getTweetsWithLinksByHandle` | `(handle, opts?)` | `from:{handle} filter:links` |

### 运行汉字

| 财产/方法 | 类型 | 说明 |
| --- | --- | --- |
| `runId` | `string` | 认证运行的ID |
| `datasetId` | `string` | 默认数据集 ID |
| `status` | `string` | 最后已知运行状态 |
| `waitForFinish(opts?)` | `Promise<RunHandle>` | 投票直到终端状态 |
| `getItems(opts?)` | `Promise<items|FullResponse>` | 获取所有数据集项目 |
| `stream()` | `AsyncGenerator<tweet>` | 对项目的同步转发器 |

## 定价

此软件包使用 [认证 Twitter Scraper Lite](https://apify.com/apidojo/twitter-scraper-lite) 使用事件定价的演员。 你只付你用过的 见 [演员定价页面](https://apify.com/apidojo/twitter-scraper-lite#pricing) 现行费率.

## 许可证

麻省理工学院

## 常见问题

### @apidojo/x-scraper 是什么？

以最快且最便宜的方式刮去X \(Twitter\)的微博\. 以开发者友好的API包装了认证的Twitter Scraper Lite演员\.

### 如何安装 @apidojo/x-scraper？

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

### @apidojo/x-scraper 支持 TypeScript 吗？

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

### @apidojo/x-scraper 支持 ESM 还是 CommonJS？

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

### @apidojo/x-scraper 需要什么版本的 Node\.js？

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

### @apidojo/x-scraper 可以商用吗？

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

### @apidojo/x-scraper 的下载量有多少？

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

### @apidojo/x-scraper 还在维护吗？

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