# @gravity-ui/expresskit 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/expresskit/

版本：3\.4\.0
npm 元数据更新时间：2026-11-02T08:17:57.029Z
中文译文更新时间：2026-11-16T23:45:16.930Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：85.6 kB，65 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：7 个
- peer 依赖：@gravity-ui/nodekit ^1\.6\.0 \|\| ^2\.0\.0
- 首次发布：2023-02-22T13:57:36.263Z
- 最新版本发布：2026-11-02T08:17:56.838Z
- 近 30 天下载量：36040（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 12 个）

## 中文简介

Express.js 基于节点Kit的应用程序的包装器

## 安装

```sh
npm install @gravity-ui/expresskit
```

也可以使用：`pnpm add @gravity-ui/expresskit`、`yarn add @gravity-ui/expresskit`、`bun add @gravity-ui/expresskit`

## README

# 快捷键

ExpressKit是轻量级 [表达式.js](https://expressjs.com/) 与 [节点Kit](https://github.com/gravity-ui/nodekit) 并提供了一些有用的特性,如请求日志,追踪支持,同源控制器和中间软件以及动词路由描述等.

安装 :

```bash
npm install --save @gravity-ui/nodekit @gravity-ui/expresskit
```

基本用途:

```typescript
import {ExpressKit} from '@gravity-ui/expresskit';
import {NodeKit} from '@gravity-ui/nodekit';

const nodekit = new NodeKit();

const app = new ExpressKit(nodekit, {
  'GET /': (req, res) => {
    res.send('Hello World!');
  },
});

app.run();
```

## 自我遥测

默认情况下,自测会发送原始请求 URL. 大型或 高心率查询字符串可以在发送数据前剥去查询参数:

```typescript
const config: Partial<AppConfig> = {
  appTelemetryChEnableSelfStats: true,
  appTelemetryChSelfStatsStripQueryParams: true,
};
```

## 社区支助方案

`config.ts`

```typescript
import type {AppConfig} from '@gravity-ui/nodekit';
import {csp} from '@gravity-ui/expresskit';

const config: Partial<AppConfig> = {
    expressCspEnable: true,
    expressCspPresets: ({getDefaultPresets}) => {
        return getDefaultPresets({defaultNone: true}).concat([
            csp.inline(),
            {csp.directives.REPORT_TO: 'my-report-group'},
        ]);
    },
    expressCspReportTo: [
        {
            group: 'my-report-group',
            max_age: 30 * 60,
            endpoints: [{ url: 'https://cspreport.com/send'}],
            include_subdomains: true,
        }
    ]
}

export default config;
```

## CSRF 保护

ExpressKit提供内置的 Cross-Site Creat Forgery (CSRF) 保护,以保护您的应用程序免受恶意的交叉源请求. CSRF中间软件会自动生成并验证用于改变状态的HTTP请求的令牌.

### 基本配置

为了启用 CSRF 保护, 请在配置中配置密钥 :

```typescript
import type {AppConfig} from '@gravity-ui/nodekit';

const config: Partial<AppConfig> = {
  // ...
  appCsrfSecret: 'your-secret-key-here',
};

export default config;
```

### 配置选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `appCsrfSecret` | `string | string[]` | \- 说吧 | **要求.** HMAC 令牌生成的秘密密钥 。 多个秘密允许密钥旋转. |
| `appCsrfLifetime` | `number` | `2592000` (30天) (中文(简体) ) | 几秒钟内就结束了 设定为 `0` 没有过期. |
| `appCsrfHeaderName` | `string` | `'x-csrf-token'` | HTTP 符号验证头名 . |
| `appCsrfMethods` | `string[]` | `['POST', 'PUT', 'DELETE', 'PATCH']` | 需要CSRF验证的HTTP方法. |

### 使用量

配置后, CSRF 保护会自动应用到所有带有指定 HTTP 方法的路径:

```typescript
import {ExpressKit, AuthPolicy} from '@gravity-ui/expresskit';
import {NodeKit} from '@gravity-ui/nodekit';

const nodekit = new NodeKit({
  config: {
    appCsrfSecret: 'your-secret-key',
    appAuthPolicy: AuthPolicy.required,

    // Ensure that your middleware sets user id to the originalContext, otherwise CSRF token generation will fail
    appAuthHandler: yourAuthHandler,
  },
});

const app = new ExpressKit(nodekit, {
  'GET /api/form': (req, res) => {
    // Token is available in request context
    res.json({csrfToken: req.originalContext.get('csrfToken')});
  },

  'POST /api/submit': (req, res) => {
    // This route automatically validates CSRF token
    res.json({message: 'Form submitted successfully'});
  },
});
```

### Per- Route 配置

您可以为特定路径禁用 CSRF 保护 :

```typescript
const app = new ExpressKit(nodekit, {
  'POST /api/webhook': {
    authPolicy: AuthPolicy.required,
    disableCsrf: true, // Disable CSRF for this route
    handler: (req, res) => {
      res.json({message: 'Webhook processed'});
    },
  },
});
```

## 缓存控制

默认情况下, ExpressKit 集 `no-cache` 所有回复都标注在信头上。 你可以在全球控制这种行为,也可以按路线控制.

### 全球配置

```typescript
const config: Partial<AppConfig> = {
  expressEnableCaching: true, // Allow caching by default
};
```

### 每个路线配置

```typescript
const app = new ExpressKit(nodekit, {
  'GET /api/cached': {
    enableCaching: true, // Allow caching for this route
    handler: (req, res) => res.json({data: 'cacheable'}),
  },
  'GET /api/fresh': {
    enableCaching: false, // Force no-cache
    handler: (req, res) => res.json({data: 'always fresh'}),
  },
});
```

路线级别 `enableCaching` 覆盖全局设置 。 缓存状态可见于 `req.routeInfo.enableCaching`。 。 。 .

## 验证和响应序列化

-   [请求验证和响应序列化](https://github.com/gravity-ui/expresskit/blob/main/docs/VALIDATOR.md) - 使用Zod schemas进行自动请求验证和响应序列化.

## 常见问题

### @gravity-ui/expresskit 是什么？

Express\.js 基于节点Kit的应用程序的包装器

### 如何安装 @gravity-ui/expresskit？

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

### @gravity-ui/expresskit 支持 TypeScript 吗？

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

### @gravity-ui/expresskit 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gravity-ui/expresskit 需要什么版本的 Node\.js？

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

### @gravity-ui/expresskit 可以商用吗？

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

### @gravity-ui/expresskit 的下载量有多少？

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

### @gravity-ui/expresskit 还在维护吗？

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

