jquery.cookie.js：一个让 Cookie 操作变简单的小工具

原创于 2026-07-17 13:30:49 发布 · 328 阅读

本内容遵循CC 4.0 BY-SA版权协议

Hi，我是前端人类学！

在前端开发中，Cookie 是一个绕不开的话题。无论是记录用户登录状态、存储偏好设置，还是追踪用户行为，Cookie 都在默默承担着数据存储的职责。但原生 JavaScript 操作 Cookie 的 API——document.cookie——说实话，用起来并不那么顺手。

于是，jquery.cookie.js 应运而生。

文章目录

一、它是什么？

jquery.cookie.js 是一个轻量级的 jQuery 插件，专门用于简化 Cookie 的读取、写入和删除操作。由 Klaus Hartl 开发，代码简洁，API 设计直观，一度成为前端项目中操作 Cookie 的首选方案。

它的核心理念很简单：把复杂的 Cookie 操作封装成几个直观的方法。

二、快速上手

使用前需要先引入 jQuery，再引入插件：

<script src="https://cdn.staticfile.org/jquery/3.4.0/jquery.min.js"></script>
<script src="https://cdn.staticfile.org/jquery-cookie/1.4.1/jquery.cookie.min.js"></script>

注意：引入顺序很重要，必须先有 jQuery，插件才能正常工作。

2.1 写入 Cookie

创建一个会话 Cookie（浏览器关闭即失效）：

$.cookie('username', '张三');

创建一个 7 天后过期的 Cookie：

$.cookie('user_token', 'abc123', { expires: 7 });

创建一个在整个网站中都可访问的 Cookie：

$.cookie('site_preference', 'dark', { path: '/' });

2.2 读取 Cookie

读取单个 Cookie：

var username = $.cookie('username'); // 返回 "张三"
var nothing = $.cookie('not_exist'); // 返回 null

读取所有 Cookie：

var allCookies = $.cookie(); // 返回 { "username": "张三", ... }

2.3 删除 Cookie

删除操作同样简单：

$.removeCookie('username'); // 删除成功返回 true，否则返回 false

但这里有个容易踩的坑：删除时必须使用与写入时完全相同的 path、domain 和 secure 选项，否则删除会失败。

// 写入时指定了 path
$.cookie('token', 'value', { path: '/' });

// 以下写法删除失败
$.removeCookie('token'); // false

// 必须带上相同的 path
$.removeCookie('token', { path: '/' }); // true

三、几个实用的配置

插件提供了两个全局配置，能让使用体验更好：

3.1 自动处理 JSON

开启后，可以直接存储和读取 JavaScript 对象，省去手动 JSON.stringify 和 JSON.parse 的步骤：

$.cookie.json = true;
$.cookie('user_settings', { theme: 'dark', language: 'zh' });
var settings = $.cookie('user_settings'); // 直接得到对象

3.2 关闭自动编码

默认情况下，Cookie 值会经过 encodeURIComponent 编码，读取时自动解码。如果不需要，可以关闭：

$.cookie.raw = true;

四、Cookie 选项详解

选项	类型	说明
`expires`	Number / Date	有效期，数字代表天数。省略则创建会话 Cookie
`path`	String	Cookie 有效路径，默认是当前页面路径。设为 `/` 则全站可用
`domain`	String	Cookie 有效域名，默认当前域名
`secure`	Boolean	是否仅通过 HTTPS 传输，默认 `false`

五、一个实际例子

假设我们要记录用户的主题偏好：

<script>
$(document).ready(function() {
    // 检查是否已有偏好
    var theme = $.cookie('theme_preference');
    if (!theme) {
        // 默认设为明亮模式
        $.cookie('theme_preference', 'light', { expires: 30, path: '/' });
        theme = 'light';
    }
    // 应用主题
    $('body').addClass('theme-' + theme);
    
    // 切换主题时更新 Cookie
    $('#theme-toggle').click(function() {
        var newTheme = $('body').hasClass('theme-light') ? 'dark' : 'light';
        $('body').removeClass('theme-light theme-dark').addClass('theme-' + newTheme);
        $.cookie('theme_preference', newTheme, { expires: 30, path: '/' });
    });
});
</script>

jquery.cookie.js 虽小，却解决了实际开发中的痛点。它把原本需要手动拼接字符串的 Cookie 操作，变成了优雅的方法调用，让代码更加清晰、可维护。

当然，作为一个诞生于 jQuery 生态的插件，它目前已经不再维护。对于新项目，原生 document.cookie 已经足够好用，或者也可以考虑独立于 jQuery 的现代 Cookie 库（如 js-cookie）。但它的设计思路和 API 风格，至今仍有参考价值。

毕竟，好的工具不在于它有多新，而在于它是否帮开发者解决了问题。这一点，jquery.cookie.js 做到了。