Node.js 版 Twitter API：2026 年如何获取 X 数据（完整指南）

作者：Sorsa 编辑部

发布于 2026 年 6 月，更新于 2026 年 7 月：反映 X 当前的按量付费定价（包括 2026 年 4 月的写入成本变化），以及 X 在 2025 年底发布的官方 Python 和 TypeScript XDK。

更新于 2026 年 7 月：把 Sorsa 价格刷新为每千批量费率，并新增了 100 次免费请求的起步优惠。

核心要点： 2026 年用 Node.js 获取 Twitter/X 数据有四条实用路线：官方 TypeScript XDK、twitter-api-v2 库、带 bearer 令牌的朴素 fetch，或一个只读的第三方 REST API。官方路线按资源计费、需要 OAuth 凭据；只需密钥的 API 适合读密集型工作。

如果你搜 “twitter api nodejs”、指望一次快速的 npm install 加一段返回推文的代码，2026 年的格局比旧教程说的更乱。X 换了定价模型、换了读取的计费方式，并首次为 JavaScript 推出了官方 SDK。多数排名靠前的 Node 指南仍在教通过一个付费开发者账号发帖，这些变化一个都没跟上。

我们开发并运营 Sorsa API 这个 Twitter/X API 替代方案，所以只读路径是我们最了解的一条。用户资料、推文、搜索结果和粉丝都以干净的 JSON 从一次 fetch 调用返回，只需 ApiKey 请求头里的一个 API 密钥，没有 OAuth 流程，也没有要等的开发者账号审批。在读密集型工作上，最多可比官方 X API 便宜 50 倍，所有套餐统一 20 次/秒，批量接口上折算为约每 1,000 条推文 $0.02，套餐 $49/月起。注册即送 100 次免费请求，无需绑卡，付费之前就能试。不是每个项目都合这个模子：有的要发帖，有的因合规必须用官方 API，有的团队只想搞懂内部原理。本指南用可用的 Node.js 代码、当前定价，以及一个会分页并在速率限制上退避的完整采集器，覆盖全部四种方法。你也可以在在线试用工具 Playground 里不写代码就测试调用。

目录

• 变了什么：2026 年的 X API 和 Node.js 工具
• Node.js 里 X API 最好的库
• 你该用哪种方式？
• 方法 1：官方 TypeScript XDK
• 方法 2：twitter-api-v2
• 方法 3：带 bearer 令牌的朴素 fetch
• 方法 4：一个只读 REST API
• 能从浏览器调用 X API 吗？
• 用 Node.js 构建一个数据采集器
• 对比：四种方法，并排
• 如何拿到你的 API 凭据
• 实战：把一个 Node 采集器从官方 API 迁走
• 常见问题
• 如何开始

变了什么：2026 年的 X API 和 Node.js 工具 {#what-changed-the-x-api-and-nodejs-tooling-in-2026}

自 2023 年以来，Node 开发者面前有三件事变了。X API 转向了没有免费版的按量付费计费，现在按资源读取收费。2026 年 4 月更新后，写入变贵了。X 还推出了首批官方 SDK，其中包括一个在 Node 里运行的 TypeScript 包，和长期存在的社区库 twitter-api-v2 并存。

按量付费是默认。 新注册没有免费版，也没有 $100 的 Basic 套餐。你先买额度、按资源付费：帖子读取每条 $0.005，用户资料每份 $0.010，粉丝或关注记录每条 $0.010。读取自己账号的数据每资源 $0.001，读取别的账号时这个费率就不适用了。标准账号还有每月 200 万次帖子读取的硬性上限。完整拆解见我们的 X API 价格详解和 X API 定价为何攀升。

写入变贵了。 2026 年 4 月更新后，标准帖子每请求 $0.015，含 URL 的帖子 $0.20。关注、点赞和引用帖子动作从自助档位移除，现在需要 Enterprise 合同。回关机器人或自动点赞器，在标准的按量付费账号上已经做不成了。

X 发布了官方 SDK。 2025 年底 X 为 Python 和 TypeScript 宣布了第一方 XDK（X Developer Kit），在其开发者公告里确认。TypeScript XDK 是 X 推出的第一个官方 JavaScript 客户端，用有类型的模型封装 v2 接口、处理分页、并支持流式。

twitter-api-v2 仍然可用。 社区库 twitter-api-v2 同时支持 v1.1 和 v2，跑读、写和私信流程，仍是使用最广的 Node 封装。现有代码用当前凭据继续工作。

旧库已死。 npm 上的 twit 和 twitter 包自 2017 年起就没有实质更新，只说 v1.1。如果一篇教程叫你 npm install twit，它已过时。

Node.js 里 X API 最好的库 {#the-best-library-for-the-x-api-in-nodejs}

对多数 Node 项目，twitter-api-v2 是最好的通用库：成熟、完全有类型，通过 bearer 令牌和 OAuth 支持读、写和私信流程。如果你想要一个精确追踪 API 规格的第一方工具，用官方 TypeScript XDK。对于只读数据采集，许多团队跳过库、用朴素 fetch 调用一个第三方 REST API，这彻底移除了 OAuth。

以下是主要选项的对比。

每个面向官方 API 的选项都走 X 的按量付费计费，所以无论你用 XDK、twitter-api-v2 还是裸 fetch 调用 X，成本都一样。你真正能控制的变量是拉取多少资源，而批量接口和按请求计费的 API，恰恰改变的就是这笔成本账。

你该用哪种方式？ {#which-approach-should-you-use}

写代码之前先挑路径。要有官方支持的读写工作，用 XDK 或 twitter-api-v2。要以最少配置大量拿只读数据，第三方 REST API 去掉了 OAuth 和审批队列。要无依赖地完全掌控，朴素 fetch 加一个 bearer 令牌就行。这个选择大体是读对写，以及你拉多少量。

如果你的项目只读取公开数据，第三方 API 去掉了 OAuth 那套繁琐：请求头里一个密钥，就能开始拉数据，没有开发者账号申请，也没有额度购买。如果你要发帖或跑写操作，通过 XDK 或 twitter-api-v2 的官方 X API 是那条路，没有第三方服务商代你发帖。改用 Python？见本指南的 Python 版。

方法 1：官方 TypeScript XDK {#method-1-the-official-typescript-xdk}

TypeScript XDK 是 X 的第一个官方 JavaScript SDK，用有类型的模型封装 v2 API、处理分页、支持流式，并在 Node.js、浏览器和 React Native 里工作。它需要 Node.js 16 或更新版本，支持 bearer 令牌、OAuth 2.0 PKCE 和 OAuth 1.0a 认证。

安装依赖：

npm install @xdevplatform/xdk

一个 bearer 令牌就足以读取公开数据。查询一份资料：

import { Client } from "@xdevplatform/xdk";

// 仅应用认证：一个 bearer 令牌覆盖对公开数据的只读访问
const client = new Client({ bearerToken: process.env.X_API_BEARER_TOKEN });

async function main() {
  const user = await client.users.getByUsername("elonmusk");
  console.log(user.data?.username, user.data?.name);
}

main();

该 SDK 为列表接口提供一个分页器。带自动分页拉取一个用户的粉丝：

import { Client, UserPaginator } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: process.env.X_API_BEARER_TOKEN });

const followers = new UserPaginator(async (token) => {
  const res = await client.users.getFollowers("44196397", {
    maxResults: 100,
    paginationToken: token,
    userfields: ["id", "name", "username"],
  });
  return { data: res.data ?? [], meta: res.meta, includes: res.includes, errors: res.errors };
});

for await (const follower of followers) {
  console.log(follower.username);
}

XDK 还暴露 client.posts 用于搜索和时间线、client.stream 用于实时信息流。当你想要官方支持、需要写权限、并且在开始一个新搭建时，它是对的选择。取舍在于：这个 SDK 年轻（截至 2026 年 2 月为 v0.5），文档仍单薄，而且每次调用都要付 X 的按资源定价。

方法 2：twitter-api-v2 {#method-2-twitter-api-v2}

twitter-api-v2 多年来一直是默认的 Node 客户端，支持 v1.1 和 v2、暴露独立的只读、读写和私信客户端，并处理分页和速率限制头，是 Node 里最接近 Python 里 Tweepy 的东西。

从 npm 安装：

npm install twitter-api-v2

从一个 bearer 令牌创建一个只读客户端并查询一份资料：

import { TwitterApi } from "twitter-api-v2";

const client = new TwitterApi(process.env.X_API_BEARER_TOKEN).readOnly;

const user = await client.v2.userByUsername("elonmusk", {
  "user.fields": ["description", "public_metrics", "created_at"],
});

console.log(user.data.username, user.data.public_metrics?.followers_count);

搜索最近 7 天。search 方法返回一个你可以直接迭代的分页器：

const search = await client.v2.search("nodejs lang:en", {
  max_results: 20,
  "tweet.fields": ["created_at", "public_metrics"],
});

for await (const tweet of search) {
  console.log(tweet.text);
}

以分页器方式获取一个用户的粉丝：

const followers = await client.v2.followers("44196397", { asPaginator: true });

for await (const follower of followers) {
  console.log(follower.username);
}

twitter-api-v2 是多数 Node 开发者的稳妥默认：久经实战、文档完善，几乎任何问题都有答案。取舍与 XDK 相同：你仍需要一个付费的 X 开发者账号、你仍按资源付费，而速率限制继承自官方 API（通常每 15 分钟窗口 300 到 900 次请求，取决于接口）。

方法 3：带 bearer 令牌的朴素 fetch {#method-3-plain-fetch-with-a-bearer-token}

没有库、没有封装。Node 18 及更新版本自带全局 fetch，所以你可以用一个 bearer 令牌、零依赖地直接调用 X API v2。这适合想完全掌控请求的开发者，或在安装包受限的环境里工作的人。

搜索近期推文：

// Node 18+ 自带全局 fetch，所以无需依赖
const headers = { Authorization: `Bearer ${process.env.X_API_BEARER_TOKEN}` };

const url = new URL("https://api.x.com/2/tweets/search/recent");
url.searchParams.set("query", "nodejs lang:en");
url.searchParams.set("max_results", "20");
url.searchParams.set("tweet.fields", "created_at,public_metrics");

const res = await fetch(url, { headers });
const data = await res.json();

for (const tweet of data.data ?? []) {
  console.log(tweet.text);
}

官方 API 用响应 meta 里的 next_token 分页。翻完每一页，带一个守卫，别让一个宽泛查询失控：

async function searchAll(query, maxPages = 10) {
  const headers = { Authorization: `Bearer ${process.env.X_API_BEARER_TOKEN}` };
  const all = [];
  let nextToken;
  let pages = 0;

  do {
    const url = new URL("https://api.x.com/2/tweets/search/recent");
    url.searchParams.set("query", query);
    url.searchParams.set("max_results", "100");
    if (nextToken) url.searchParams.set("next_token", nextToken);

    const res = await fetch(url, { headers });
    const data = await res.json();
    all.push(...(data.data ?? []));
    nextToken = data.meta?.next_token;
    pages += 1;
  } while (nextToken && pages < maxPages);

  return all;
}

想要最少依赖、或者在调试 API 行为时，这管用。缺点很明显：分页、错误码、限速和重试都得你自己处理。生产环境的数据管道，你最终会重建一个封装。这个方法仍然需要一个 X 开发者账号和按量付费额度，用一个 bearer 令牌做只读访问。

方法 4：一个只读 REST API {#method-4-a-read-only-rest-api}

如果一个项目只读取公开 Twitter 数据，第三方 REST API 能彻底跳过官方 API。没有 OAuth、没有申请步骤、没有额度购买流程，就是请求头里一个密钥，加返回的 JSON。对只读负载来说，这去掉了官方 API 的大部分配置，把数据采集变成朴素的 HTTP 调用。

这是不用开发者账号获取 X 数据的实用路线。下面是用 Sorsa、只用 fetch 的写法。

获取一份用户资料：

const headers = { ApiKey: process.env.SORSA_API_KEY };

const res = await fetch("https://api.sorsa.io/v3/info?username=elonmusk", { headers });
const user = await res.json();

console.log(`@${user.username}: ${user.display_name}`);
console.log(`Followers: ${user.followers_count}`);

用完整的网页操作符集搜索推文。搜索接口每页返回约 20 条推文和一个用于下一页的 next_cursor：

const res = await fetch("https://api.sorsa.io/v3/search-tweets", {
  method: "POST",
  headers: { ApiKey: process.env.SORSA_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ query: "nodejs lang:en", order: "latest" }),
});

const { tweets, next_cursor } = await res.json();

for (const tweet of tweets) {
  console.log(`${tweet.likes_count} likes: ${tweet.full_text}`);
}

复杂查询就像在高级搜索里那样组合操作符，完整的操作符列表在我们的高级搜索语法参考里，而这个接口搜的是完整推文存档，不只是最近 7 天。想要深入版，有一篇专门讲通过 API 搜索推文的指南。

拉取一份粉丝列表。一次请求返回最多 200 份资料：

const headers = { ApiKey: process.env.SORSA_API_KEY };

const res = await fetch("https://api.sorsa.io/v3/followers?username=elonmusk", { headers });
const { users, next_cursor } = await res.json();

console.log(`Got ${users.length} followers in one request`);

用批量接口一次调用取多达 100 条推文，返回完整的推文对象（含指标和作者），只算一次请求：

const res = await fetch("https://api.sorsa.io/v3/tweet-info-bulk", {
  method: "POST",
  headers: { ApiKey: process.env.SORSA_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    tweet_links: ["1782368585664626774", "1782368585664626775"],
  }),
});

const { tweets } = await res.json();

每个推文响应都携带完整的作者资料和公开指标（likes_count、retweet_count、reply_count、quote_count、view_count），所以通过 API 读取推文指标和获取粉丝列表不花额外调用。请求头是 ApiKey，基础 URL 是 https://api.sorsa.io/v3，而响应形状与 API 文档完全一致。

能从浏览器调用 X API 吗？ {#can-you-call-the-x-api-from-the-browser}

不能。你无法从客户端 JavaScript 安全地直接调用 X API。每个已认证请求都需要一个 bearer 令牌或 OAuth secret，而浏览器代码里的任何东西，对任何打开开发者工具的人都可见。多数情况下调用还会跨域失败。标准做法是用一个小型服务端代理，它持有凭据，只暴露你前端所需的数据。

形状很简单。一个在 Vercel、Cloudflare Workers、Netlify 或任意主机上的无服务器函数，从一个环境变量读取密钥、在服务端调用 API、并把干净的 JSON 返回给浏览器：

// /api/tweets  （无服务器函数，在服务端运行，不在浏览器里）
export default async function handler(req, res) {
  const r = await fetch("https://api.sorsa.io/v3/search-tweets", {
    method: "POST",
    headers: { ApiKey: process.env.SORSA_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ query: req.query.q, order: "latest" }),
  });
  const data = await r.json();
  res.status(200).json(data);
}

浏览器随后调用你自己的 /api/tweets 接口、从不直接调用数据服务商，密钥也从不离开服务器。官方 TypeScript XDK 技术上能在浏览器和 React Native 里运行，但这不改变规则：把一个 bearer 令牌发到客户端代码就等于暴露了它。所以无论你用哪个客户端，都要把凭据留在一个服务端接口后面。

用 Node.js 构建一个数据采集器 {#building-a-data-collector-in-nodejs}

生产采集器在单次调用之外还需要三样东西：游标分页、页数守卫（防止宽泛查询耗尽额度），以及碰到速率限制时的重试。下面是一个对着搜索接口的完整只读采集器，用 next_cursor 分页、并在 429 上退避。

async function collectTweets(query, maxPages = 20) {
  const endpoint = "https://api.sorsa.io/v3/search-tweets";
  const headers = { ApiKey: process.env.SORSA_API_KEY, "Content-Type": "application/json" };
  const collected = [];
  let cursor;
  let pages = 0;

  while (pages < maxPages) {
    const body = { query, order: "latest" };
    if (cursor) body.next_cursor = cursor;

    const res = await fetch(endpoint, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    });

    // 固定每秒 20 次请求的限制：遇到 429，等一秒再重试同一页
    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, 1000));
      continue;
    }

    const data = await res.json();
    collected.push(...(data.tweets ?? []));

    cursor = data.next_cursor;
    pages += 1;
    if (!cursor) break;
  }

  return collected;
}

// 用法
const tweets = await collectTweets("from:OpenAI -is:retweet");
console.log(`Collected ${tweets.length} tweets`);

我们对着搜索接口重建自己的采集器时发现，真正要紧的变量不是库，而是每次调用返回多少资源、以及计费对此如何反应。统一的每秒限制比逐接口的窗口更好控节奏：遇到 429 等一秒，不用追踪一个重置时间戳。游标机制见分页指南，官方侧的细节在我们的 X API 速率限制参考里。同一个循环改改接口和 body，就能干净地换到 /user-tweets、/followers 或 /mentions。

对比：四种方法，并排 {#comparison-four-methods-side-by-side}

四种方法在两个维度上清晰分野：你能不能写入，以及怎么计费。三条官方 API 路线都需要开发者账号、按资源计费。只读 API 用写权限换来一个单一密钥和按请求计费。

这个分野告诉你该挑哪个：要发帖或跑写操作，那是官方 API 通过 XDK 或 twitter-api-v2 的地盘。而要以固定、可预测的价格做读密集型访问，只读 API 是更便宜、更简单的路线，返回的还是同样的公开数据。

读取上的成本差距完全来自计费单位。官方 API 对响应里每条帖子和每份作者资料收费；按请求计费的 API 无论返回多少条目都只收一次请求。

对读密集型工作，按资源模型就是把一件简单的事做贵的方式，这也是为什么一旦你越过每月约 1 万次读取，按请求计费就胜出。写入是例外：发帖和私信只活在官方 API 上，所以写入密集型项目不管读取成本如何都属于那里。

如何拿到你的 API 凭据 {#how-to-get-your-api-credentials}

用官方 API，就在 developer.x.com 创建开发者账号、同意开发者条款、说明用例，再创建一个 Project 和 App 来生成 API 密钥、API secret、bearer 令牌和 access token。第一次调用之前先买额度，因为没有免费版。用只读第三方 API，就注册、生成一个密钥、在请求头里带上，没有申请或审批步骤。注册即送 100 次免费请求，所以第一次调用之前没什么要买的。

任一凭据都存进一个环境变量、绝不放在源码里：

# .env
X_API_BEARER_TOKEN=your-x-bearer-token
SORSA_API_KEY=your-sorsa-api-key

如果你在把现有的官方 API 代码迁过去，迁移指南把官方接口和字段名映射到对应项，让你不用重写逻辑就能换掉传输层。

实战：把一个 Node 采集器从官方 API 迁走 {#in-practice-moving-a-node-collector-off-the-official-api}

一个约 12 人的社交分析初创公司找到我们，正跑着一个建在 twitter-api-v2 上的夜间 Node 采集器。代码没问题；账单有问题。每次运行都按帖子读取和作者资料付费，而每月 200 万次帖子读取的上限逼着团队随着被追踪账号列表增长而盯着量。

修法是换传输层，不是重写。他们保留了采集逻辑和调度，把 twitter-api-v2 客户端换成对着搜索和 /followers 接口的朴素 fetch 模式，并把 OAuth 换成一个 ApiKey 请求头。因为每次请求最多返回 20 条推文或 200 份粉丝资料、而不是按资源计费，同样的夜间拉取只花了此前的一个零头，读密集的部分约省 30 到 50 倍。一个每秒限制取代了每月上限，成为唯一需要控节奏的东西。对只读负载来说，按资源模型此前一直是把简单事做贵的方式。

常见问题 {#faq}

有面向 Node.js 的官方 Twitter API SDK 吗？

有。2025 年底 X 发布了一个官方 TypeScript XDK，用 npm install @xdevplatform/xdk 安装，可在 Node.js、浏览器和 React Native 里运行，是 X 推出的第一个官方 JavaScript 客户端，带有类型的模型、自动分页和流式。成熟的社区库 twitter-api-v2 仍是有力的替代，同时支持 API v1.1 和 v2。

Twitter API 最好的 npm 包是什么？

对多数 Node 项目，twitter-api-v2 是最好的通用选择：成熟、完全有类型，支持读、写和私信流程，并处理分页和速率限制重试。要精确追踪 API 规格的第一方支持，用官方 TypeScript XDK。旧的 twit 和 twitter 包自 2017 年起无人维护、只说 API v1.1，所以避开它们。

能在客户端 JavaScript 里用 Twitter API 吗？

不能直接用。每个已认证的 X API 调用都需要一个 bearer 令牌或 OAuth secret，而浏览器代码里放的任何凭据，对任何检查页面的人都暴露，加上多数调用会跨域失败。标准模式是用一个小型服务端代理（比如一个无服务器函数），它持有密钥、调用 API、只返回你前端所需的数据。

如何在 Node.js 里不用开发者账号获取推文？

调用一个只读第三方 REST API。用 Sorsa，你注册、拿一个 API 密钥、在 ApiKey 请求头里带上、把一个查询 POST 到搜索接口，全都在一次 fetch 调用里完成。没有 OAuth 流程、没有应用审核、没有额度购买，而 JSON 直接映射到 JavaScript 对象，每条推文里都含作者资料。

2026 年 Twitter API 对一个 Node.js 应用要花多少钱？

在官方 X API 上按资源付费：帖子读取每条 $0.005，用户资料每份 $0.010，标准帖子每条 $0.015，含 URL 的帖子 $0.20，每月上限 200 万次帖子读取。一次返回 20 条推文的搜索，一旦算上作者资料就是 $0.30。Sorsa 按请求计费，批量接口上折算为约每 1,000 条推文 $0.02、每 1,000 份资料约 $0.01，套餐 $49/月起。注册即送 100 次免费请求，无需绑卡，付费之前就能测。

在 Node.js 里如何处理 Twitter API 速率限制？

官方 API 按 15 分钟窗口限制请求（通常 300 到 900，取决于接口），撞上时返回一个带 reset 头的 429。twitter-api-v2 和 XDK 自动退避；用朴素 fetch，你读取这些头、重试前等待。Sorsa 这类按请求计费的 API 用每秒限制（20 次/秒），所以遇到 429 等一秒、再重试同一次调用。

twitter-api-v2 支持 X API v2 吗？

支持。twitter-api-v2 同时支持 API v1.1 和 v2，带独立的只读、读写和私信客户端，以及完整的 TypeScript 类型，与当前的 bearer 令牌和 OAuth 认证配合。它确实需要一个买了额度的付费 X 开发者账号，因为在按量付费模型下官方 API 没有免费版。

如何开始 {#getting-started}

挑一个方法、跑上面某个示例。

• 只读数据： 从 Sorsa 控制台拿一个密钥，设为 SORSA_API_KEY，跑任意方法 4 的代码片段。注册即送 100 次免费请求，所以这些示例在你买任何东西之前就能跑。结构化 X 数据不到一分钟就落到你的终端，快速上手带你走一遍第一次调用。套餐和限制见定价页面。
• 读写： 在 developer.x.com 创建一个开发者账号、买额度，并用你的 bearer 令牌跑 XDK 或 twitter-api-v2 示例。
• 对比服务商： 对只读选项的更广视角，见 Twitter API 替代方案对比。

审校：Keksich（Sorsa 创始人，X API 研究者）

我们如何核实本指南

本指南在 2026 年 6 月一边每天运营该 API、一边撰写并核实。官方 XDK 的细节（@xdevplatform/xdk 包、Node.js 16+ 支持、自动分页、流式，以及三种认证方法）来自 X 的 TypeScript XDK 文档及其上线公告。twitter-api-v2 的能力（只读、读写和私信客户端，以及 userByUsername、search 和 followers 方法）对照其包文档核查。X API 定价反映当前的按量付费模型，包括 2026 年 4 月的写入成本变化。Sorsa 接口行为、按请求批量和套餐定价来自 Sorsa API 文档；团队的更多信息见我们的关于页面。会变的数字（比如下载量和 GitHub star）以描述而非引用给出；要拿当前价格，产品内文档才是准确来源。