# @curveball/session 中文文档
规范地址：https://npmcn.com/package/%40curveball/session/
版本：1\.0\.1
npm 元数据更新时间：2024-11-06T21:21:00.408Z
中文译文更新时间：2026-11-13T07:15:06.313Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40curveball/session
原文对照：https://npmcn.com/package/%40curveball/session/?lang=original
项目主页：https://github.com/curveball/session#readme
源码仓库：https://github.com/curveball/session
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：32.3 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>= 18
- 运行依赖：1 个
- peer 依赖：@curveball/kernel ^1
- 首次发布：2018-09-06T09:43:07.843Z
- 最新版本发布：2024-11-06T21:21:00.130Z
- 近 30 天下载量：2137（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 0 个）
## 中文简介
使用 HTTP cookie 存储会话
## 安装
```sh
npm install @curveball/session
```
也可以使用：`pnpm add @curveball/session`、`yarn add @curveball/session`、`bun add @curveball/session`
## README
# 曲线球会话中端软件
此软件包增加了对会话的支持 [曲线球](https://github.com/curveball/) 框架.
特征 :
- 懒去来. 只有店里有东西,它才会开始会话.
- 如果空出会话数据, 也会自动擦除会话数据 .
- 它提供了生成和验证CSRF令牌的功能.
## 安装
```
npm install @curveball/session
```
## 从0.5和以下版本升级
如果您正在从0.5.x版本或更早的版本升级, 此软件包将引入 a 业连间休息自0.6起.
0.5会话数据见 `ctx.state.session` 财务报告和审定财务报表 `ctx.state.sessionId`但是这个已经移到 `ctx.session` 财务报告和审定财务报表 `ctx.sessionId`。 。 。 .
## 开始
### 添加中间软件
```typescript
import session from '@curveball/session';
app.use(session({
store: 'memory',
});
```
这将在曲线球上添加内元会话存储 。 这家店主要是 是用来测试的.
下面是另一个有更多选项的例子:
```typescript
import session from '@curveball/session';
app.use(session({
store: 'memory',
cookieName: 'MY_SESSION',
expiry: 7200,
cookieOptions: {
secure: true,
path: '/',
sameSite: true,
},
});
```
- `cookieName` - 更新HTTP Cookie的名称。 这是 `CB` 默认.
- `expiry` - 会话消失前的不活动秒数. 这是3600秒默认。 它只涉及人类的寿命 它不会影响饼干参数.
- `cookieOptions` - 如果设置了, 将覆盖默认的 cookie 选项 。 名单 支持选项的文档中可找到 \[cookie\] 软件包 \[3\].
### 使用会话存储器
在自己的控制器和中间软件中,可以设置并更新会话数据 通过 `ctx.session` 属性.
```typescript
app.use( ctx => {
// Running this will create the session
ctx.session = { userId: 5 };
ctx.response.body = 'Hello world';
});
```
### 删除会话
要删除一个开放式会话,只需清除会话数据:
```typescript
app.use( ctx => {
// Running this will create the session
ctx.session = null;
});
```
### 重新生成会话编号 .
如果您清除了会话 ID, 但还有数据, 中间软件会 删除旧会话并自动创建新会话 id:
```typescript
app.use( ctx => {
// This will kill the old session and start a new one with the same data.
ctx.sessionId = null;
});
```
### CSRF 符号支持
要获得表格的CSRF令牌,中间软件提供 `getCsrf()` 函数 :
```typescript
app.use( async ctx => {
// Obtain a CSRF token for HTML forms:
const csrfToken = await ctx.getCsrf();
});
```
建议将这个符号嵌入到 HTML 格式中:
```html
```
然后继续 `POST` 请求中,您可以很容易地用 `validateCsrf` 函数。 如果符号不正确, 将自动导致 403 错误 :
```typescript
app.use(route.post('/form-submit', ctx => {
// Throws error if csrf-token was not supplied or incorrect
ctx.validateCsrf();
}));
```
## API 密码
宜自创店铺作产品用. 最后这个 工程可能还会再添加几个默认存储 .
在此之前,您必须执行以下接口:
```typescript
interface SessionStore {
set(id: string, values: SessionValues, expire: number): Promise;
get(id: string): Promise,
delete(id: string): Promise,
newSessionId(): Promise,
}
```
`SessionValues` 仅仅是一个按键 > 值对象. `expire` 表示为unix 时间戳.
## 常见问题
### @curveball/session 是什么？
使用 HTTP cookie 存储会话
### 如何安装 @curveball/session？
在项目目录运行 npm install @curveball/session，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@curveball/kernel（^1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @curveball/session 支持 TypeScript 吗？
该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/curveball\_\_session 是否存在。
### @curveball/session 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @curveball/session 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>= 18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @curveball/session 可以商用吗？
@curveball/session 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @curveball/session 的下载量有多少？
根据 npm 官方下载统计，@curveball/session 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,137 次，日均约 71 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @curveball/session 还在维护吗？
最新版本 1\.0\.1 发布于 2024/11/07（2 年前）；至今共发布 22 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。