某天打开 GitHub 通知，看到一个用户提的 issue 标题写着：

建议投稿到「阮一峰的科技爱好者周刊」

我笑了笑，没太当回事 —— 一个刚开源不久的小工具，能被周刊收录的概率并不大。

但几周之后，我真的在 issue-397 里看到了自己的项目。那一刻，比拿到 star 还开心 —— 因为这意味着，一个原本只是为了「让前端不再绕道 Python 拿股票数据」而写的小工具，被更多需要它的人看到了。

随之而来的变化也很真实：

  • 📦 版本一路迭代到 v1.10.0
  • ⭐ GitHub 收获 940+ stars
  • 🐛 收到并解决了 10+ 个 issues —— 从 “希望支持板块概念”、”希望支持基金行情”，到 “希望搜索接口返回股票/ETF 类型”，每一条都让 SDK 变得更扎实

这篇文章想做的事很简单：把 stock-sdk 当前的全景能力，完整地讲一遍。如果你是前端工程师、量化爱好者、做行情看板的独立开发者，或者正在用 AI 工具搭金融小应用，希望它能帮你少走点弯路。

它解决了什么问题？

如果你是前端开发者，大概率遇到过这些场景：

  • 想做个行情看板 / 个股监控 demo，但发现成熟的工具基本都在 Python 生态（akshare、tushare、efinance……）
  • 不想为了拿点行情数据，专门维护一个 Node / Python 后端
  • 财经接口返回的格式五花八门：腾讯返回 ~ 分隔字符串、东方财富返回 GBK 编码、新浪要处理 jsonp 包裹…
  • AkShare 很强，但它是 Python 的，浏览器里跑不起来

stock-sdk 想做的事情很纯粹：

让前端工程师，用最熟悉的 JavaScript / TypeScript，优雅地获取股票行情数据。

零依赖、双端运行（浏览器 + Node.js ≥ 18）、完整 TypeScript 类型，装上就能用。

1
2
3
4
5
6
7
8
import { StockSDK } from 'stock-sdk';

const sdk = new StockSDK();
const quotes = await sdk.getSimpleQuotes(['sh000001', 'sz000858', 'sh600519']);

quotes.forEach(q => {
  console.log(`${q.name}: ${q.price} (${q.changePercent}%)`);
});

10 行代码，浏览器或 Node 都能跑。

全景能力一览

经过十几个版本的迭代，stock-sdk 现在覆盖的能力面已经相当宽。下面按维度拆开讲。

1. 多市场实时行情

A 股、港股、美股、公募基金，一套 SDK 全覆盖：

方法 覆盖范围
getFullQuotes / getSimpleQuotes A 股 / 指数全量 + 简要行情
getHKQuotes 港股
getUSQuotes 美股
getFundQuotes 公募基金

而且 SDK 内置批量并发拉取能力 —— 一次调用就能拿到全市场 5000+ A 股的行情：

1
2
3
4
5
const allQuotes = await sdk.getAllAShareQuotes({
  batchSize: 300,
  concurrency: 5,
  onProgress: (completed, total) => console.log(`${completed}/${total}`),
});

无需后端服务，浏览器里直接跑通。

2. K 线数据：日线 / 周线 / 月线 / 分钟线 / 分时

不止是当前行情，历史 K 线和盘中分时也都有：

  • getHistoryKline / getHKHistoryKline / getUSHistoryKline —— 三大市场的日 / 周 / 月 K 线
  • getMinuteKline —— 1 / 5 / 15 / 30 / 60 分钟 K 线
  • getTodayTimeline —— 当日分时走势

港股、美股的 K 线类型从 v1.9.1 起拆分为 HKHistoryKline / USHistoryKline，各自带 currency 和时区元信息 —— 不用再手动处理「这条数据是哪国货币、几点开盘」的繁琐细节。

3. 技术指标：14 个常用指标内置

K 线拿到了，下一步通常是算指标。SDK 内置了一整套：

1
2
MA / EMA / WMA / MACD / BOLL / KDJ / RSI / WR
BIAS / CCI / ATR / OBV / ROC / DMI / SAR / KC

最方便的是 getKlineWithIndicators —— 一次返回 K 线 + 你指定的指标，不用自己再算一遍：

1
2
3
4
5
const data = await sdk.getKlineWithIndicators({
  code: 'sh600519',
  period: 'day',
  indicators: ['MA(5)', 'MA(20)', 'MACD', 'BOLL'],
});

4. 板块数据：行业 + 概念

getIndustryList / getIndustrySpot / getIndustryConstituents / getIndustryKline / getIndustryMinuteKline —— 行业板块的「列表 / 行情 / 成分股 / K 线 / 分时」一套打通。

概念板块同理，5 个对称的 getConcept* 方法。

如果你做过板块轮动的 demo，应该知道凑齐这套数据有多麻烦。SDK 把这一层抹平了。

5. 期货 & 期权：相对小众但完整

很多人不知道这套 SDK 也支持期货和期权：

  • 期货：国内期货 K 线、全球期货实时行情 + K 线、期货库存数据、COMEX 黄金/白银库存
  • 期权：中金所股指期权 T 型报价、ETF 期权当日分钟 / 历史日 K / 5 日分钟、商品期权报价 + K 线、期权龙虎榜

对做衍生品研究、写策略 demo 的开发者，这一块很顶用。

6. 资金流向 & 北向资金

A 股玩家最关心的资金面数据，全在这：

  • getIndividualFundFlow / getMarketFundFlow —— 个股、大盘资金流历史
  • getFundFlowRank / getSectorFundFlowRank —— 今日 / 3 日 / 5 日 / 10 日资金流排名
  • getNorthboundMinute / getNorthboundHoldingRank / getNorthboundHistory / getNorthboundIndividual —— 北向 / 南向资金的分时、汇总、持股排行、历史、个股持仓

7. 龙虎榜 + 大宗交易 + 融资融券

游资跟踪、机构动向、杠杆资金，这套国内独有的市场数据也覆盖：

  • 龙虎榜：详情、个股统计、机构买卖、营业部排行、席位明细
  • 大宗交易：市场总览、明细、按股票每日统计
  • 融资融券：账户统计 + 标的明细

8. 涨停板 / 盘口异动

A 股短线玩家高频需要的「涨停板池」和「盘口异动」：

  • getZTPool —— 涨停 / 昨日涨停 / 强势 / 次新 / 炸板 / 跌停，6 大股池
  • getStockChanges —— 22 种盘口异动（火箭发射、大笔买入、封涨停……）
  • getBoardChanges —— 当日板块异动详情

9. 基金深度数据（v1.10.0 新增）

最新版本针对公募基金做了一次大幅扩展，这块是阮一峰周刊那波关注之后最常被催的能力之一（issue #16：希望支持基金行情）：

方法 说明
getFundNavHistory 历史净值（单位 + 累计），全历史一次返回
getFundEstimate 当日实时估值（含 T-1 单位净值 + 盘中估算）
getFundRankHistory 同类排名走势（每日近三月排名 + 百分位）
getFundDividendList 基金 / ETF 分红明细，全市场，按年份分页

对做基金 / ETF 看板的同学，这套数据基本就是「即插即用」。

10. 扩展能力：搜索、交易日历、分红、外链

一些「不抢眼但很省心」的小功能：

  • search —— 按代码 / 名称 / 拼音搜索（issue #24 反馈后增加了 ETF 类型区分）
  • getTradingCalendar + isTradingDay() 等工具 —— A 股交易日历
  • getDividendDetail —— 个股分红派送（issue #13 的需求）
  • generateSearchExternalLinks(result) —— 一键生成东方财富 / 雪球外链

11. 请求治理：重试 / 限流 / 熔断 / 错误码

如果你打算把它放进生产环境，会喜欢这一层：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const sdk = new StockSDK({
  retry: { maxRetries: 2, baseDelay: 500 },
  providerPolicies: {
    eastmoney: {
      timeout: 12000,
      rateLimit: { requestsPerSecond: 3, maxBurst: 3 },
    },
  },
});

try {
  await sdk.getSimpleQuotes(['sh600519']);
} catch (error) {
  if (error instanceof HttpError) {
    console.log(error.status, error.statusText);
  }
  console.log(getSdkErrorCode(error)); // HTTP_ERROR / NETWORK_ERROR / TIMEOUT ...
}
  • 全局可配重试 + 退避
  • 每个数据源（腾讯 / 东方财富 / 新浪 / 天天基金）都可以独立设置 timeout / 限流策略
  • 标准化错误码（getSdkErrorCode），不破坏原始错误类型
  • 内置「全局 mutex」防止浏览器并发踩同一接口（issue #12：用一阵被东财封了 —— 这条 issue 直接推动了 P1 并发安全治理）

12. AI / MCP 就绪

最后一块，也是这一年增长最猛的方向：让 AI 工具直接调用行情数据。

stock-sdk 配套发布了 stock-sdk-mcp —— 一个标准的 MCP Server，支持 Cursor / Claude Desktop / Codex CLI / Gemini CLI 等主流 AI 工具。配置只需要一行：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "stock-sdk": {
      "command": "npx",
      "args": ["-y", "stock-sdk-mcp"]
    }
  }
}

接好之后，就可以直接对 AI 说：

“帮我看一下贵州茅台最近的 MACD 走势”
“今天涨停板有哪些？”
“北向资金最近 5 天加仓最多的 10 只股票是什么？”

内置 4 个专业 AI Skills：技术分析 / 智能选股 / 市场概览 / 实时监控。

一些数字

写到这里盘了一下从开源到现在的数据：

  • 940+ GitHub stars
  • 68 forks
  • v1.10.0 —— 在持续迭代
  • 10+ closed issues —— 每一条社区反馈都尽量当周内回应
  • 被阮一峰周刊 issue-397 收录

老实说，做开源不是为了数字，但当你看到 issue 里有人说 “用了一阵被封了”、”希望支持基金”、”我用 ts 重写了 akshare 的可转债板块”—— 你会意识到，写代码这件事，原来真的可以被很多陌生人接住。

后续在做什么？

  • 完善基金一侧的数据深度（盘中估值的多源对比、定投回测工具）
  • 把 RequestClient 的可观测性进一步打开（per-provider 的 metrics）
  • MCP Skills 继续扩展，让 AI 在金融数据这块做得更顺手
  • 期待你的下一条 issue

资源链接

如果这篇文章让你想试一试，下面这些链接你应该会用到：

如果觉得有用，欢迎 Star ⭐；如果踩坑了，欢迎来 issues 拍砖。下一版本，咱们见。

Happy Coding!