# @admiral-vrm/sdk-node 中文文档

规范地址：https://npmcn.com/package/%40admiral-vrm/sdk-node/

版本：1\.1\.3
npm 元数据更新时间：2026-03-16T14:24:48.645Z
中文译文更新时间：2026-11-06T00:49:59.567Z
软件包许可：Apache-2\.0 WITH Commons-Clause

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

原始 npm 页面：https://www.npmjs.com/package/%40admiral-vrm/sdk-node
原文对照：https://npmcn.com/package/%40admiral-vrm/sdk-node/?lang=original

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

- 包体积（解压后）：76.9 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- peer 依赖：next \>=13，react \>=16，react-dom \>=16，@edge-runtime/cookies \>=6，@noble/hashes ^1\.7\.0
- 首次发布：2026-02-03T22:05:51.869Z
- 最新版本发布：2026-03-16T14:24:48.453Z
- 近 30 天下载量：7804（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

诺德JS的上将SDK简化了使用上将API用于服务器侧JavaScript所写应用的过程.

## 安装

```sh
npm install @admiral-vrm/sdk-node
```

也可以使用：`pnpm add @admiral-vrm/sdk-node`、`yarn add @admiral-vrm/sdk-node`、`bun add @admiral-vrm/sdk-node`

## README

# 诺德JS的SDK上将

提供一个简单的界面,用于使用海军上将的 API 应用软件 服务器侧 JavaScript. 拜访我们 [上将](https://getadmiral.com/) 为了更多 资料.

## 所需资源

节点.js 18 或以后(见 `engines` (原始内容存档于2018-09-21). in package.json.

## 安装

将软件包安装到您的工程 :

```bash
npm install @admiral-vrm/sdk-node
# or
yarn add @admiral-vrm/sdk-node
```

这个软件包 **同行依赖关系** (单位:千美元)`@edge-runtime/cookies`, (中文(简体) ), `@noble/hashes` v1.x,在使用这些特性时加上React/Next). Next.js的应用软件一般满足这些要求. 如果在非邻接环境(如快取或平地节点)中使用 SDK,在需要时可手动安装等同位素. 使用 `@noble/hashes` v1.x; v2.x 使用不同的导出路径, 尚未支持 .

```bash
npm install @edge-runtime/cookies @noble/hashes@^1.7.0
```

## 配置

-   **属性ID** (要求):你的上将地产ID(例如. `"A-1234-1"`) (中文(简体) ).
-   **密钥** (在使用"保护"时被推荐):用于签下访客代币的秘密. 在生产中设定一个强而独特的值;否则将使用默认值(不适合生产). 也可以通过 `ADMIRAL_TOKEN_SECRET_KEY`。 。 。 .
-   **代理服务器**: 可选。 使用时 `proxyAdmiral: true`设置 `proxy.host` (可选) `scheme`, (中文(简体) ), `prefix`) (中文(简体) ).
-   **保护选项**: 可选。 保护/伙伴 API: `partnerApiEndpoint`, (中文(简体) ), `cacheTimeout`. API 证书在保护集成内配置(见示例).

## 文档

### 上将

这个 `Admiral` 班级是SDK上将的主要班级. 它包含配置 用于上将物体,例如财产ID、环境、保护以及 代理,还有附加参数.

```
export const admiral = new Admiral({
  propertyID: "A-1234-1",
  environment: "production",
  protect: true,
  proxyAdmiral: true,
  tokenSecretKey: process.env.ADMIRAL_TOKEN_SECRET_KEY, // recommended for production
  proxy: {
    host: "host.com",
    scheme: "https",
  },
});
```

该类提供下列方法:

### 获取“ 可能的手提箱 (): 字符串 \[\]

返回可能用作前缀的上将前缀处理器阵列 当使用代理功能时.

### 获取 PossibleProxyPath 前缀 (): 字符串 \[\]

返回匹配代理路由的路径前缀(例如. `["/abcde.../", "/fghij.../"]`) (中文(简体) ). 没有 I/O 检查或诊断 前缀随时间旋转;作为 运行时的路由提示,而不是静态的不变量.

### 获取当前ProxyPath Prefix (): 字符串

返回当前(今天)代理路径前缀(例如. `"/abcde.../"`),或 `""` 若为 无。 与 `getPossibleProxyPathPrefixes()[0]`没有I/O.

### 是Proxy Request( urlOrReq: string QQ Middleware Request):布尔

如果请求或 URL 匹配代理路径, 则返回真实 。 接受完整的 URL, 路径名,或中间软件请求。 没有 I/O. 在叫 SDK 跳过前使用 非埃米尔请求(门-第一模式).

### 获取ProxyRoutingInfo (): { 处理器: 字符串 \[; 前缀: 字符串 \[; 当前前缀: 字符串; 生成At: 数字 }

返回当前代理处理器、路径前缀、当前(今天)前缀,以及 生成时间。 仅供管理员/调试使用;限制访问,不公开曝光.

### 获取 SSR Bootstraps (): 保证

获取用于服务器侧渲染的上将脚本 。 返回承诺 包含:

-   `admiral`: 一组靴子拖曳脚本字符串, 每个字符串应该是脚本标记

### 获取 Bootstraps (): 承诺 < string \[\] >

获取将军的脚本。 返回包含一系列脚本的保证 字符串.

### commerceSSR Bootstraps(载荷:AdmiralSSR BootstrapWrapper,格式:"html" QQ"反应"="反应"):反应. 反应节点\[\]

将用于服务器侧渲染的上将脚本作为 React 组件 . 从取回SSR Boots后取出一个靴子包裹有效载荷,并返回一系列 反应脚本元素.

参数:

-   `payload`: 含有靴子脚本阵列的对象 `admiral` 键

### 处理请求中软件( req: Middleware Request):承诺

处理上将的中件功能,包括代理请求和保护 函数。 返回包含中间软件响应的许诺 :

-   `response`: 响应对象(可选)
-   `headers`: 页眉对象(可选)
-   `cookies`: reswerCookies对象(可选)

参数:

-   `req`: 中间软件 请求包含收到请求细节的对象

您可以使用拆分处理器和一个门来进行更多的控制 :

-   **处理程序** - 仅限代理 请求时使用 一个代理路径( 例如: 之后) `isProxyRequest(url)`) (中文(简体) ).
-   **手柄 保护请求中软件( req)** - 仅保护(钥匙、饼干重置, 海军上将-保护-街区头). 无代理.

## 安装 API 和代理行为

-   **靴子( 安装 API ):** 你可以继续使用克龙 或建立步骤 获取脚本( 例如 ) . `fetchSSRBootstraps()` 或安装 API) 把它们藏在CDN上 您不需要调用安装 API 每个用户的运行时间 .
-   **代理服务器 :** 中间软件中的网络回转只在请求时发生 匹配代理路径前缀之一(Admiral runtime脚本/beacon流量). 正常的页面加载、登录和app API 调用不会击中代理服务器 门:呼叫 `admiral.isProxyRequest(url)` 首先并且只在 它返回真实(或当URL是保护符/重设URL). 见 下个js 和 expressjs 的门首中件模式示例.
-   **为什么基于路径的代理?** CNAME 致第三方主机将被封杀 堵车 基于路径的代理服务器保留您主机上的请求 (单位:千美元)`yourdomain.com/<prefix>/...`),所以主办方保持第一党,而不是 已过滤 。 披露任何路径诊断(例如:. `getProxyRoutingInfo()`仅限 给管理员/调试对象,不公开.

## 用下个.js和反应

详情请参见下例,并附上一个完整的例子 关于如何使用海军上将SDK和Next.js的文件.

这个 `ProtectEmbed` 组件是用于嵌入 将功能保护为 React 应用程序 .

## 使用快递.js/节点.js

更多信息请参见expressjs 示例 和关于如何使用SDK上将 与快递.

这个 `ProtectHTMLEmbed` 库允许将带有保护功能的 HTML 嵌入到 您的应用程序不使用 React .

## 常见问题

### @admiral-vrm/sdk-node 是什么？

诺德JS的上将SDK简化了使用上将API用于服务器侧JavaScript所写应用的过程\.

### 如何安装 @admiral-vrm/sdk-node？

在项目目录运行 npm install @admiral-vrm/sdk-node，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@edge-runtime/cookies（\>=6）、@noble/hashes（^1\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @admiral-vrm/sdk-node 支持 TypeScript 吗？

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

### @admiral-vrm/sdk-node 支持 ESM 还是 CommonJS？

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

### @admiral-vrm/sdk-node 需要什么版本的 Node\.js？

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

### @admiral-vrm/sdk-node 可以商用吗？

@admiral-vrm/sdk-node 使用 Apache-2\.0 WITH Commons-Clause 许可。声明的许可为 Apache-2\.0 WITH Commons-Clause，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @admiral-vrm/sdk-node 的下载量有多少？

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

### @admiral-vrm/sdk-node 还在维护吗？

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