catalog/repos/adrianmg--league-sdk.md

英雄联盟API开发工具包

TypeScript SDK 英雄联盟 Riot API npm

league-sdk

一个完整类型化的 TypeScript SDK，用于访问 Riot 英雄联盟 API。

为什么选择这个 SDK？

直接使用原始 Riot API 需要调用多个端点、处理复杂路由并手动转换数据。本 SDK 将一切化繁为简：

原始 API（多次调用，手动处理）：

// 1. 通过 Riot ID 获取账户（区域端点）
const account = await fetch(`https://asia.api.riotgames.com/riot/account/v1/accounts/by-riot-id/Hide%20on%20bush/KR1?api_key=${key}`);
const { puuid } = await account.json();

// 2. 获取召唤师数据（平台端点）
const summoner = await fetch(`https://kr.api.riotgames.com/lol/summoner/v4/summoners/by-puuid/${puuid}?api_key=${key}`);
const { id: summonerId } = await summoner.json();

// 3. 获取段位数据（平台端点，不同 ID）
const leagues = await fetch(`https://kr.api.riotgames.com/lol/league/v4/entries/by-puuid/${puuid}?api_key=${key}`);
const ranked = await leagues.json();
const soloQ = ranked.find(q => q.queueType === 'RANKED_SOLO_5x5');

// 4. 手动计算胜率
const winRate = soloQ.wins / (soloQ.wins + soloQ.losses);

使用 league-sdk：

const player = await client.players.getByRiotId('Hide on bush', 'KR1');
const soloQ = await player.getSoloQueueStats();
console.log(`${soloQ.tier} ${soloQ.division} - ${(soloQ.winRate * 100).toFixed(1)}% 胜率`);

快速上手

安装

npm install league-sdk
# 或
bun add league-sdk

API 密钥

前往 developer.riotgames.com 获取密钥。开发者密钥有效期 24 小时（每秒 20 次，每 2 分钟 100 次）。如需永久密钥，请注册产品。

快速示例

import { LolClient } from 'league-sdk';

const client = new LolClient({
  apiKey: process.env.RIOT_API_KEY!,
  platform: 'kr'
});

// 获取玩家及其段位数据
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
const soloQ = await player.getSoloQueueStats();

// 获取近期对局
const matches = await client.matches.getForPlayer(player.puuid, { count: 5 });
for (const match of matches) {
  const p = match.getParticipant(player.puuid)!;
  console.log(`${p.championName}: ${p.kills}/${p.deaths}/${p.assists}`);
}

开发环境

bun install && bun test

# 适用于 AI Agent 的技能
npx skills add https://github.com/adrianmg/league-sdk --skill league-sdk

功能特性

服务	说明	示例
Players（玩家）	通过 Riot ID 或 PUUID 查询	client.players.getByRiotId('Name', 'Tag')
Matches（对局）	对局历史与详情	client.matches.getForPlayer(puuid)
Mastery（熟练度）	英雄熟练度数据	client.mastery.getForPlayer(puuid)
Live Game（实时对局）	当前对局观战信息	client.liveGame.getForPlayer(puuid)
Status（状态）	服务器健康状态	client.status.get('euw1')
Challenges（挑战）	挑战任务进度	client.challenges.getPlayerProfile(puuid)
Clash（冠军杯）	赛事信息	client.clash.getPlayer(puuid)
Data Dragon（静态数据）	静态数据（无需密钥）	client.dataDragon.getChampions()

实体对象

// 玩家
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
player.puuid; player.riotId; player.level;
await player.getSoloQueueStats();

// 对局
const match = await client.matches.getById('EUW1_1234567890');
match.gameMode; match.gameDurationFormatted; match.winner;
const p = match.getParticipant(puuid)!;
p.kills; p.deaths; p.assists; p.kda; p.csPerMinute;

常量与工具函数

import { PLATFORMS, QUEUES, isRankedQueue, formatRank, compareRanks } from 'league-sdk';

PLATFORMS.EUW1           // 'euw1'
isRankedQueue(420)       // true（单双排）
formatRank('DIAMOND', 'II')  // "钻石 II"
compareRanks('DIAMOND', 'II', 'PLATINUM', 'I')  // 1（钻石 > 铂金）

错误处理

类型化错误：NotFoundError、RateLimitError（含 retryAfter）、AuthenticationError。

资源下载

npx league-sdk-assets --output ./assets --all

也可通过 league-sdk/scripts 使用程序化 API。

请求限速

内置限速器（每秒 20 次，每 2 分钟 100 次）。可通过 rateLimiter 选项配置，或使用 client.getRateLimitStatus() 查看当前状态。

示例服务器

RIOT_API_KEY=your-key bun run example/server.ts

支持的平台

平台	区域	位置
na1	americas	北美
br1	americas	巴西
la1	americas	拉丁美洲北部
la2	americas	拉丁美洲南部
euw1	europe	欧洲西部
eun1	europe	欧洲北欧及东部
tr1	europe	土耳其
ru	europe	俄罗斯
kr	asia	韩国
jp1	asia	日本
oc1	sea	大洋洲
ph2	sea	菲律宾
sg2	sea	新加坡
th2	sea	泰国
tw2	sea	台湾
vn2	sea	越南

许可证

MIT

致谢

本项目在 GitHub Copilot 和 Claude 等 AI 编程工具的协助下开发完成。