Cookies.js

Cookies.js 是一个轻量级的客户端 JavaScript 库，让 Cookie 管理变得简单高效。
GitHub 仓库：https://github.com/ScottHamper/Cookies

一、核心特性

• ✅ 完全符合 RFC6265 标准
• ✅ 跨浏览器兼容
• ✅ 超轻量（压缩后仅约 1.2 KB gzipped）
• ✅ 无任何依赖
• ✅ 公共领域（Public Domain）开源协议
• ✅ 支持 AMD / CommonJS 模块加载器

二、浏览器兼容性

以下浏览器均通过了 Cookies.js 的自动化测试：

• Chrome
• Firefox 3+
• Safari 4+
• Opera 10+
• Internet Explorer 6+

三、获取库

方式1：直接下载

• v1.2.3 压缩版（~1.2 KB gzipped）
• v1.2.3 未压缩版（~1.9 KB gzipped）

方式2：NPM 安装

npm install cookies-js

方式3：Bower 安装

bower install cookies-js

四、特殊环境使用：CommonJS/Node（无 window 对象）

在没有原生 window 对象的环境中（如 Node.js 配合 jsdom），Cookies.js 会导出一个工厂方法，需要传入 window 实例：

var jsdom = require('jsdom');
var window = jsdom.jsdom().parentWindow;
var Cookies = require('cookies-js')(window);

// 之后就可以正常使用 Cookies 了

五、编码注意事项

RFC6265 对 Cookie 的键和值有严格的字符限制。为了支持任意字符，Cookies.js 会对不允许的字符进行 UTF-8 格式的 URI 编码。因此，在服务端处理 Cookie 时，也需要使用对应的 UTF-8 URI 编码/解码方式。

.NET 用户特别提醒

不要使用 HttpUtility.UrlEncode 和 HttpUtility.UrlDecode 处理 Cookie 键值：

• HttpUtility.UrlEncode 会错误地将空格转义为 '+'，并将所有转义序列转为小写；
• HttpUtility.UrlDecode 会错误地将所有 '+' 还原为空格。

正确做法：使用 System.Uri.EscapeDataString 和 System.Uri.UnescapeDataString。

六、API 参考

方法

1. Cookies.set(key, value [, options])

别名：Cookies(key, value [, options])
设置 Cookie，若 Cookie 不存在则创建，返回 Cookies 对象（支持链式调用）。

可选参数 options

选项	描述	默认值
path	Cookie 生效的路径字符串	"/"
domain	Cookie 生效的域名字符串	undefined
expires	Cookie 过期时间：可以是秒数（Number）、可解析的日期字符串、Date 对象	undefined（会话 Cookie，关闭浏览器失效）
secure	是否仅在 SSL（HTTPS）下生效	false

示例用法

// 基础设置
Cookies.set('key', 'value');

// 链式调用
Cookies.set('key', 'value').set('hello', 'world');

// 带额外选项
Cookies.set('key', 'value', { 
  domain: 'www.example.com', 
  secure: true 
});

// 设置过期时间
Cookies.set('key', 'value', { expires: 600 }); // 10分钟后过期
Cookies.set('key', 'value', { expires: '01/01/2012' });
Cookies.set('key', 'value', { expires: new Date(2012, 0, 1) });
Cookies.set('key', 'value', { expires: Infinity }); // 永不过期（实际受浏览器限制）

// 使用别名
Cookies('key', 'value', { secure: true });

2. Cookies.get(key)

别名：Cookies(key)
返回指定键的 Cookie 值（取最局部作用域的 Cookie）。

示例用法

// 先设置
Cookies.set('key', 'value');

// 获取
Cookies.get('key'); // "value"

// 使用别名
Cookies('key'); // "value"

3. Cookies.expire(key [, options])

别名：Cookies(key, undefined [, options])
删除指定 Cookie，返回 Cookies 对象。

可选参数 options

选项	描述	默认值
path	Cookie 生效的路径字符串（需与设置时一致）	"/"
domain	Cookie 生效的域名字符串（需与设置时一致）	undefined

示例用法

// 设置并获取
Cookies.set('key', 'value').get('key'); // "value"

// 删除并尝试获取
Cookies.expire('key').get('key'); // undefined

// 使用别名
Cookies('key', undefined);

属性

1. Cookies.enabled

布尔值，表示浏览器是否启用了 Cookie。

示例用法

if (Cookies.enabled) {
  Cookies.set('key', 'value');
}

2. Cookies.defaults

对象，用于设置 Cookie 的默认选项（设置和删除时都会生效）。

可选默认选项

同 Cookies.set 的 options 参数：path、domain、expires、secure。

示例用法

// 设置默认选项
Cookies.defaults = {
  path: '/',
  secure: true
};

// 之后设置的 Cookie 会自动应用默认选项
Cookies.set('key', 'value'); // 自动带 path='/' 和 secure=true

// 删除时也会应用默认 path
Cookies.expire('key'); // 自动用 path='/' 删除