# @eggjs/cookies 中文文档

规范地址：https://npmcn.com/package/%40eggjs/cookies/

版本：4\.1\.0
npm 元数据更新时间：2026-10-07T08:17:47.411Z
中文译文更新时间：2026-11-13T09:19:11.687Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40eggjs/cookies
原文对照：https://npmcn.com/package/%40eggjs/cookies/?lang=original
项目主页：https://github.com/eggjs/egg/tree/next/packages/cookies
源码仓库：https://github.com/eggjs/egg

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

- 包体积（解压后）：25 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：2 个
- 首次发布：2024-06-23T09:33:08.722Z
- 最新版本发布：2026-10-07T08:17:46.990Z
- 近 30 天下载量：6558（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 36 个）

## 中文简介

鸡蛋的饼干模块

## 安装

```sh
npm install @eggjs/cookies
```

也可以使用：`pnpm add @eggjs/cookies`、`yarn add @eggjs/cookies`、`bun add @eggjs/cookies`

## README

# @eggjs/cookies

[![NPM version](https://img.shields.io/npm/v/@eggjs/cookies.svg?style=flat-square)](https://npmjs.org/package/@eggjs/cookies) [![npm download](https://img.shields.io/npm/dm/@eggjs/cookies.svg?style=flat-square)](https://npmjs.org/package/@eggjs/cookies)

为 egg 提供 cookie 操作的封装。

```ts
ctx.cookies = new Cookies(ctx, keys[, defaultCookieOptions]);

ctx.cookies.get('key', 'value', options);
ctx.cookies.set('key', 'value', options);
```

## 初始化

初始化时需要传递 Array 类型 的keys 参数，否则无法使用 cookies 的 `signed` 和 `encrypt` 功能。

每次设置或读取 signed cookie 或者 encrypt cookie 的时候，会用 keys 进行加密。每次加密都通过 keys 数组的第一个 key 进行加密，解密会从先到后逐个 key 尝试解密。读取 signed cookie 时，如果发现不是用第一个 key 进行加密时，会更新签名为第一个 key 加密的值。读取 encrypt cookie 时不会进行更新操作。

### `defaultCookieOptions`

全局默认配置：

-   autoChips - `Boolean` 是否开启 [CHIPS](https://developers.google.com/privacy-sandbox/3pcd/chips#security_design) 的自动适配方案， 会自动给 Cookie 新增一个 `_CHIPS-` 为前缀的分区 Cookie，优先读取非分区 Cookie，读取失败则尝试读取 `_CHIPS-` 前缀的同名 Cookie 适配三方 Cookie 禁止逻辑。 一旦 `cookies.set` 设置 `partitioned=true`，那么会强制忽略 `autoChips` 参数。

## 设置 cookie

通过 `cookies.set(key, value, options)` 的方式来设置一个 cookie。其中 options 支持的参数有：

-   path - `String` cookie 的有效路径，默认为 `/`。
-   domain - `String` cookie 的有效域名范围，默认为 `undefined`。
-   expires - `Date` cookie 的失效时间。
-   maxAge - `Number` cookie 的最大有效时间，如果设置了 maxAge，将会覆盖 expires 的值。
-   secure - `Boolean` 是否只在加密信道中传输，注意，如果请求为 http 时，不允许设置为 `true`，https 时自动设置为 `true`。
-   partitioned - `Boolean` 是否设置独立分区状态（[CHIPS](https://developers.google.com/privacy-sandbox/3pcd/chips)）的 Cookie。注意，只有 `secure` 为 `true` 的时候此配置才会生效。
-   removeUnpartitioned - `Boolean` 是否删除非独立分区状态的同名 cookie。注意，只有 `partitioned` 为 `true` 的时候此配置才会生效。
-   httpOnly - `Boolean` 如果设置为 `true`，则浏览器中不允许读取这个 cookie 的值。
-   overwrite - `Boolean` 如果设置为 `true`，在一个请求上重复写入同一个 key 将覆盖前一次写入的值，默认为 `false`。
-   signed - `Boolean` 是否需要对 cookie 进行签名，需要配合 get 时传递 signed 参数，此时前端无法篡改这个 cookie，默认为 `true`。
-   encrypt - `Boolean` 是否需要对 cookie 进行加密，需要配合 get 时传递 encrypt 参数，此时前端无法读到真实的 cookie 值，默认为 `false`。
-   priority - `String` 表示 cookie 优先级的字符串，可以设置为 `'low'`, `'medium'`, `'high'`，默认为 `undefined`。[A Retention Priority Attribute for HTTP Cookies](https://datatracker.ietf.org/doc/html/draft-west-cookie-priority)

## 读取 cookie

通过 `cookies.get(key, value, options)` 的方式来读取一个 cookie。其中 options 支持的参数有：

-   signed - `Boolean` 是否需要对 cookie 进行验签，需要配合 set 时传递 signed 参数，此时前端无法篡改这个 cookie，默认为 true。
-   encrypt - `Boolean` 是否需要对 cookie 进行解密，需要配合 set 时传递 encrypt 参数，此时前端无法读到真实的 cookie 值，默认为 false。

## 删除 cookie

通过 `cookie.set(key, null)` 来删除一个 cookie。如果传递了 `signed` 参数，签名也会被删除。

## License

[MIT](https://npmcn.com/package/%40eggjs/cookies/LICENSE)

## Contributors

[![Contributors](https://contrib.rocks/image?repo=eggjs/egg)](https://github.com/eggjs/egg/graphs/contributors)

Made with [contributors-img](https://contrib.rocks/).

## 常见问题

### @eggjs/cookies 是什么？

鸡蛋的饼干模块

### 如何安装 @eggjs/cookies？

在项目目录运行 npm install @eggjs/cookies，或使用 pnpm add / yarn add / bun add。

### @eggjs/cookies 支持 TypeScript 吗？

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

### @eggjs/cookies 支持 ESM 还是 CommonJS？

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

### @eggjs/cookies 需要什么版本的 Node\.js？

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

### @eggjs/cookies 可以商用吗？

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

### @eggjs/cookies 的下载量有多少？

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

### @eggjs/cookies 还在维护吗？

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