# @btravstack/http-server 中文文档

规范地址：https://npmcn.com/package/%40btravstack/http-server/

版本：0\.58\.0
npm 元数据更新时间：2026-11-07T21:12:15.076Z
中文译文更新时间：2026-11-08T17:41:11.086Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40btravstack/http-server
原文对照：https://npmcn.com/package/%40btravstack/http-server/?lang=original
项目主页：https://github.com/btravstack/btravstack#readme
源码仓库：https://github.com/btravstack/btravstack

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

- 包体积（解压后）：432 kB，55 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：0 个
- peer 依赖：jose ^6，unthrown ^5\.7\.0，openid-client ^6，@btravstack/di ^0\.58\.0，@btravstack/core ^0\.58\.0，@btravstack/config ^0\.58\.0，@btravstack/contract ^0\.58\.0
- 首次发布：2026-08-25T16:16:34.911Z
- 最新版本发布：2026-11-07T21:12:14.607Z
- 近 30 天下载量：9614（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

协议中性节点 HTTP 运行时间、请求单位和认证@btravstack/core

## 安装

```sh
npm install @btravstack/http-server
```

也可以使用：`pnpm add @btravstack/http-server`、`yarn add @btravstack/http-server`、`bun add @btravstack/http-server`

## README

# @btravstack/http-server 页面存档备份,存于互联网档案馆

协议中性节点 HTTP 运行时间 `@btravstack/core`它拥有 听着, `HttpHandler` 设置端口, 每个请求一个单位, 认证助手, 准备,和优雅的排水。 每个协议都从它的 自有软件包 :

-   [`@btravstack/orpc-server`](https://npmcn.com/package/%40btravstack/orpc-server) 用于合同首个ORPC和OpenAPI线路.
-   [`@btravstack/htmx-server`](https://npmcn.com/package/%40btravstack/htmx-server) 用于隐藏 HTML 碎片.
-   [`@btravstack/graphql-server`](https://npmcn.com/package/%40btravstack/graphql-server) 为瑜伽计划.

选择部署的答案包。 这个 [命令 API](https://npmcn.com/package/examples/order-api) 运行 ORPC 和 htmx [图QL 网关](https://npmcn.com/package/examples/order-graphql-api) 分开运行和呼叫 aPI通过客户端软件包发出命令.

```sh
pnpm add @btravstack/http-server @btravstack/core @btravstack/config \
  @btravstack/di unthrown
```

HTTP 运行时间由 `HttpModule` (单位:千美元)`@btravstack/orpc-server`)或(或) `GraphqlModule` (单位:千美元)`@btravstack/graphql-server`页:1 `HttpHandler` 成员路线 以最长的匹配前缀. `defineAuth()` 名称共享方案,不选择 协议。 JWT,会话和OIDC的帮助者继续 `/jwt`, (中文(简体) ), `/session` 财务报告和审定财务报表 `/oidc`。选入 `/oidc-tokens` 在 应用程序提供共享存储,并在整个系统进行更新和登录 复制品。 将其管理端口通过登录和会话验证器; 证书不在校长和会议饼干之外。 设定 `oidc()`是因为 `postLogoutRedirectUri` 或者说 `HTTP_OIDC_POST_LOGOUT_REDIRECT_URI` 改为 供应商注册的绝对返回 URI 允许 RP 启动登录 。 登录 在解析后, 仅将保留的身份代号作为提供者的登录提示 删除全权证书。 没有这个设置, 登录保持其现有的 无参数的行为。 见 [服务器侧 OIDC 令牌](https://btravstack.github.io/btravstack/reference/http-server#server-side-oidc-tokens)。 。 。 .

`protectedResource()` 出版保护资源元数据(RFC 9728) 一个资源, `protectedResourcePerHost()` 给每个服务主持人一个 见 [hTTP 引用](https://btravstack.github.io/btravstack/reference/http-server) 用于请求单位,安全,配置和关闭行为.

应用程序验证器可以返回 `AuthenticatorUnavailable` 当 a 依赖无法决定。 它停止了认证行走和每个HTTP 答题返回 `503`,通过 `Observers`。见 [认证依赖终止](https://btravstack.github.io/btravstack/reference/http-server#authentication-dependency-outages)。 。 。 .

`jwtAuthenticator()` 返回时 `Unauthenticated` 当发行者的密钥集是 无法使用或无法使用 。 答案确定响应: 通常 `401`, (中文(简体) ), 或一个 `303` 在 htmx 路径上登录浏览器的重定向 已配置登录路径 。 它报告断电经过 `Observers` 与 `component: "jwt"`, (中文(简体) ), `name: "verify"`, (中文(简体) ), `outcome: "error"` 和界限 `reason`,而不是返回 `AuthenticatorUnavailable`见 [JWT发行商出厂政策](https://npmcn.com/package/%40btravstack/http-server/AUTH.md#surface) 和它的区别 [认证依赖终止](https://npmcn.com/package/%40btravstack/http-server/AUTH.md#authentication-dependency-outages)。 。 。 .

请求范围提供者可注射 `HttpRequestMetadata` 要解码信头, 方法和 URL 独立于认证。 奔跑时间播下永恒的种子 每一请求单位的快照和取消信号;在 应用范围提供者。 见 [HTTP 参考](https://btravstack.github.io/btravstack/reference/http-server#non-authentication-request-metadata)。 。 。 .

`jwtVerifier()` 打开 `/jwt` 独立提供缓存签名证据验证 hTTP认证方案。 弹出 `JwtVerifier` 提供预期 观众人数 `verify({ token, audience })` 调用; 发行者和 JWKS 信任保留 启动时固定。 见 [签名证据](https://btravstack.github.io/btravstack/reference/http-server#signed-evidence-for-another-recipient)。 。 。 .

## JWT 核查人选项

-   `issuer`:给所需的发行者打针.
-   `jwks`: 将可信任的密钥集终点标出 .
-   `variablePrefix`:命名发行者/JWKS环境前缀.
-   `algorithms`: 将签名允许列表标出 .
-   `clockToleranceSec`:指针已失效/不留余地前.
-   `allowInsecureJwks`: 明确允许非loopback清晰文本开发密钥.
-   `port`:命名第二个发行人的验证能力.

默认和配置语义在 [HTTP 参考](https://btravstack.github.io/btravstack/reference/http-server#signed-evidence-for-another-recipient)。 。 。 .

## 听取选项

-   `port`, (中文(简体) ), `hostname`:绑住听者.
-   `headersTimeoutMs`, (中文(简体) ), `requestTimeoutMs`:绑定请求接收.
-   `keepAliveTimeoutMs`: 响应后绑定闲置可重复使用的连接.
-   `keepAliveTimeoutBufferMs`:将实际保留寿命延长到其公布的预算之外.
-   `socketTimeoutMs`: 请求和答复进展期间约束不活动.

每个变量都有匹配的环境变量;默认值,零语义和节点 兼容性位于 [HTTP 参考](https://btravstack.github.io/btravstack/reference/http-server#httpconfig-and-the-environment)。 。 。 .

## 常见问题

### @btravstack/http-server 是什么？

协议中性节点 HTTP 运行时间、请求单位和认证@btravstack/core

### 如何安装 @btravstack/http-server？

在项目目录运行 npm install @btravstack/http-server，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：unthrown（^5\.7\.0）、@btravstack/di（^0\.58\.0）、@btravstack/core（^0\.58\.0）、@btravstack/config（^0\.58\.0）、@btravstack/contract（^0\.58\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @btravstack/http-server 支持 TypeScript 吗？

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

### @btravstack/http-server 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @btravstack/http-server 需要什么版本的 Node\.js？

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

### @btravstack/http-server 可以商用吗？

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

### @btravstack/http-server 的下载量有多少？

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

### @btravstack/http-server 还在维护吗？

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