# @blizzard-api/client 中文文档

规范地址：https://npmcn.com/package/%40blizzard-api/client/

版本：5\.5\.2
npm 元数据更新时间：2026-10-20T17:06:35.868Z
中文译文更新时间：2026-11-08T11:23:44.070Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40blizzard-api/client
原文对照：https://npmcn.com/package/%40blizzard-api/client/?lang=original
项目主页：https://github.com/Pewtro/blizzard-api/tree/main/packages/client
源码仓库：https://github.com/Pewtro/blizzard-api

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

- 包体积（解压后）：43 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.13\.0 \|\| ^24 \|\| ^26
- 运行依赖：1 个
- peer 依赖：@blizzard-api/core 4\.2\.0
- 首次发布：2024-03-27T20:01:46.557Z
- 最新版本发布：2026-10-20T17:06:35.430Z
- 近 30 天下载量：1789（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 15 个）

## 中文简介

与暴雪战斗整合的节点. js客户端.net api.

## 安装

```sh
npm install @blizzard-api/client
```

也可以使用：`pnpm add @blizzard-api/client`、`yarn add @blizzard-api/client`、`bun add @blizzard-api/client`

## README

# @ 暴风雪- api/ 客户端

这个软件包提供了一个客户端,意在与一个或多个专用于暴风雪游戏的软件包一起使用.

目前可用的软件包有:

-   `@blizzard-api/classic-wow`
-   `@blizzard-api/d3`
-   `@blizzard-api/hs`
-   `@blizzard-api/sc2`
-   `@blizzard-api/wow`

## 安装

```sh
npm i @blizzard-api/client
```

## 使用量

```ts
import { createBlizzardApiClient } from '@blizzard-api/client';
//or
import createBlizzardApiClient from '@blizzard-api/client';
import { wow } from '@blizzard-api/wow';

const client = await createBlizzardApiClient({
  key: 'environment.blizzardClientId',
  secret: 'environment.blizzardClientSecret',
  origin: 'eu',
});

//Response will automatically be typed with the appropriate values
const response = await client.sendRequest(wow.commodities());

console.log(response);
                ^ typeof AuctionHouseCommoditiesResponse
```

## 客户选项

`createBlizzardApiClient` 接受一个 `ClientOptions` 对象 :

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `key` | `string` | 对 | 你的Blizzard API客户身份证. |
| `secret` | `string` | 对 | 你的Blizzard API客户端的秘密. |
| `origin` | `Origins` | 对 | 与该区域交谈,例如:. `'eu'`, (中文(简体) ), `'us'`, (中文(简体) ), `'kr'`, (中文(简体) ), `'tw'`, (中文(简体) ), `'cn'`。 。 。 . |
| `locale` | `Locales` | 没有 | 例如,请求答复的地方. `'en_GB'`。默认为 `origin`。 。 。 . |
| `token` | `string` | 没有 | 先前存在的访问符 如果提供,则在仍然有效时予以验证并重新使用. |
| `kyOptions` | `KyOptions` | 没有 | 转交基础 [`ky`](https://github.com/sindresorhus/ky) 举个例子. |

### 自动刷新令牌

`createBlizzardApiClient` 选择第二个参数, `onTokenRefresh`,用于控制访问符的管理方式:

-   `true` (default)——客户端在创建时获得一个令牌,并在到期前不久自动安排刷新.
-   `false` ——客户端在未获得或未安排任何令牌的情况下被退回. 你负责打电话 `getAccessToken`编号 :`setAccessToken` 你自己来.
-   `(token: AccessToken) => void` - 行为就像 `true`以每件新获得的符文,都引用你的召喚.

```ts
const client = await createBlizzardApiClient({ key, secret, origin: 'eu' }, (token) => {
  console.log('Refreshed token', token.access_token);
});
```

如果有的话 `token` 在选项中提供,首先验证。 仍然有效的令牌被再用,在快过期时会安排刷新;过期或无效的令牌立即被刷新. 刷新计时器是 `unref`"d,所以他们从来没有保持你的流程.

## 发送请求

将一个资源从一个游戏包传递到 `sendRequest`。从资源中推断出响应类型,并可以提供每个请求的覆盖:

```ts
import { wow } from '@blizzard-api/wow';

const response = await client.sendRequest(wow.commodities(), {
  locale: 'de_DE',
  // Any other ClientOptions field can be overridden per request,
  // including kyOptions for retries, timeouts, hooks, etc.
  kyOptions: { timeout: 10_000 },
});
```

`sendRequest` 决定: `undefined` 返回的终点 `204 No Content` 或为一空相.

## API 密码

客户端回来了 `createBlizzardApiClient` (实例 `BlizzardApiClient`揭露:

| 成员 | 说明 |
| --- | --- |
| `defaults` | 已解决的默认 `key`, (中文(简体) ), `secret`, (中文(简体) ), `origin`, (中文(简体) ), `locale`,当前 `token`。 。 。 . |
| `sendRequest(resource, options?)` | 发送资源请求并返回其输入的响应(或) `undefined` 用于空回复). |
| `getAccessToken(options?)` | 使用客户端证书流请求新的访问令牌 . |
| `refreshAccessToken(options?)` | 请求新的访问符并存储在客户端上. |
| `validateAccessToken(options?)` | 在Blizzard的OAuth端点验证访问令牌. |
| `setAccessToken(token)` | 手动设定用于后续请求的访问符. |
| `getRequestUrl(resource, options?)` | 在不发送的情况下构建一个资源的请求 URL . |
| `getRequestConfig(resource, options?)` | 构建标题并搜索资源参数而不发送 . |

## 认证

请参看 [battle.net 文档](https://develop.battle.net/documentation/guides/getting-started) 如何获得布莱扎德API证书的指南.

## 常见问题

### @blizzard-api/client 是什么？

与暴雪战斗整合的节点\. js客户端\.net api\.

### 如何安装 @blizzard-api/client？

在项目目录运行 npm install @blizzard-api/client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@blizzard-api/core（4\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @blizzard-api/client 支持 TypeScript 吗？

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

### @blizzard-api/client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @blizzard-api/client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.13\.0 \|\| ^24 \|\| ^26。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @blizzard-api/client 可以商用吗？

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

### @blizzard-api/client 的下载量有多少？

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

### @blizzard-api/client 还在维护吗？

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