JavaScript Cookie操作全解析：从基础API到安全实践

1. 从“记住我”到购物车：Cookie的前世今生与核心价值

如果你做过前端开发，或者哪怕只是写过几行网页脚本，大概率都跟Cookie打过交道。它可能是你实现“记住我”登录功能时第一个想到的方案，也可能是你处理用户购物车数据时顺手就用的存储工具。但你真的了解这个看似简单的“小饼干”吗？为什么在LocalStorage、SessionStorage、IndexedDB等现代Web存储方案层出不穷的今天，Cookie依然在许多关键场景中无法被替代？今天，我们就来彻底拆解JavaScript中Cookie的常见API操作，这不仅仅是几个方法的罗列，更是理解Web基础通信机制、用户状态管理以及安全边界的一次深度探索。

Cookie的本质，是服务器发送到用户浏览器并保存在本地的一小块数据。它会在浏览器下次向同一服务器再发起请求时被携带并发送到服务器。这个简单的机制，构成了早期Web维持用户状态（如登录态）的基石。与纯粹的前端存储（如LocalStorage）不同，Cookie的生命周期、作用域和安全性都与其HTTP特性紧密绑定。理解这一点，是灵活、正确操作Cookie API的前提。本文将从一个资深开发者的视角，带你从原理到实践，从基础操作到高级技巧，再到避坑指南，完整掌握Cookie的方方面面。无论你是想巩固基础的新手，还是希望深入理解其工作机制的老手，都能在这里找到干货。

2. Cookie的底层原理：它不只是个“存储”

在动手写代码之前，我们必须先搞清楚Cookie是怎么工作的。很多人把Cookie简单地等同于一个前端键值对存储，这是最大的误解。Cookie是HTTP协议的一部分，它的行为规则是由RFC标准定义的，浏览器和服务器都遵循这套规则来协同工作。

2.1 HTTP头中的旅行：Set-Cookie与Cookie

Cookie的旅程始于服务器的一个响应。当服务器决定要给客户端设置一个Cookie时，它会在HTTP响应头中添加一个Set-Cookie字段。这个字段的格式包含了键值对以及一系列控制属性。

HTTP/1.1 200 OK Content-Type: text/html Set-Cookie: sessionId=abc123; Expires=Wed, 21 Oct 2026 07:28:00 GMT; Path=/; Secure; HttpOnly

浏览器接收到这个响应后，会按照指令将sessionId=abc123这个键值对以及相关的属性（过期时间、路径、安全标志等）存储起来。之后，每当浏览器向同一域名、符合路径规则的地址发起请求时，都会自动在请求头中带上这个Cookie。

GET /user/profile HTTP/1.1 Host: www.example.com Cookie: sessionId=abc123; theme=dark

这就是为什么Cookie能维持登录状态——服务器在登录成功后设置一个包含用户身份的Cookie，浏览器后续的所有请求都会自动“出示”这个身份凭证。而LocalStorage则完全不具备这个“自动携带”的特性，它只是一个纯粹的前端沙箱。

2.2 核心属性详解：控制Cookie行为的开关

仅仅一个键值对是远远不够的。Cookie的强大和复杂，都体现在它的一系列属性上。这些属性决定了Cookie何时生效、在哪里生效、以及如何被访问。

• Expires/Max-Age：生命周期控制器

  • Expires指定一个具体的GMT格式的过期时间点。例如：Expires=Wed, 21 Oct 2026 07:28:00 GMT。时间不准确或格式错误会导致Cookie立即失效，这是新手常踩的坑。
  • Max-Age指定从现在开始Cookie存在的秒数，优先级高于Expires。例如：Max-Age=2592000（30天）。设置为0或负数会立即删除Cookie。
  • 如果两者都不设置，创建的就是一个会话期Cookie。它仅在当前会话（即浏览器标签页）有效，关闭标签页或浏览器后就会被清除。很多临时性的状态（如表单草稿）适合用这种Cookie。

• Domain与Path：作用域的双重锁

  • Domain指定了哪些主机可以接收该Cookie。如果不设置，默认为当前文档的源（不包含子域名），且Cookie不会被发送到子域名。如果设置为.example.com，则www.example.com、api.example.com等所有子域名都能接收到此Cookie。这里有个关键点：你只能设置为当前域或其父域，不能设置为毫不相关的域。
  • Path指定了URL路径前缀，只有路径匹配时才会发送Cookie。例如，Path=/admin的Cookie，只有在访问/admin或/admin/users等子路径时才会被携带，访问/home则不会。这常用于将Cookie限制在网站的特定模块，提升安全性和减少不必要的网络传输。

• Secure与HttpOnly：安全卫士

  • Secure：这是一个布尔属性。如果设置，Cookie只会在通过HTTPS协议加密的请求中被发送。在HTTP请求中，浏览器会直接忽略它。这在防止中间人攻击窃取会话Cookie时至关重要。最佳实践是：生产环境的所有敏感Cookie（尤其是会话ID）都必须标记为Secure。
  • HttpOnly：这也是一个布尔属性。如果设置，JavaScript的document.cookieAPI将无法访问该Cookie。这个Cookie只能由浏览器在HTTP请求中自动发送给服务器。这是预防跨站脚本攻击（XSS）窃取用户Cookie的最有效手段之一。用户的身份认证Token几乎都应该被标记为HttpOnly。

• SameSite：对抗CSRF的现代盾牌

  • 这是相对较新但极其重要的属性，用于控制Cookie在跨站请求中是否被发送。它有三个值：
    • Strict：最严格。完全禁止在跨站请求中发送Cookie。即使用户从邮件点击链接跳转到你的网站，之前的登录Cookie也不会被发送，用户需要重新登录。安全性最高，用户体验可能受影响。
    • Lax（默认值，现代浏览器的默认行为）：一种平衡方案。允许在顶级导航（如点击链接）的跨站请求中发送Cookie，但阻止在跨站的子资源请求（如图片、iframe、AJAX）中发送。这能有效防御大多数CSRF攻击，同时不影响正常的跳转登录体验。
    • None：允许跨站发送Cookie，但前提是必须同时设置Secure属性（即必须使用HTTPS）。主要用于需要跨站共享状态的场景，如第三方登录、嵌入式支付等。

理解这些属性，你就掌握了Cookie的灵魂。接下来，我们看看如何用JavaScript与这个“灵魂”对话。

3. 原生JavaScript Cookie API：一把双刃剑

document.cookie是浏览器提供的原生操作接口。它设计得非常原始，用起来有些“反直觉”，但理解它有助于你明白底层发生了什么。

3.1 读取：一个充满陷阱的字符串

读取所有Cookie非常简单：

const allCookies = document.cookie; console.log(allCookies); // 输出：”sessionId=abc123; theme=dark; userId=42”

你会发现，它返回的是一个由分号和空格拼接的字符串，而不是一个方便操作的对象。你需要手动解析它：

function getCookie(name) { const cookieArr = document.cookie.split('; '); for (let cookie of cookieArr) { const [key, value] = cookie.split('='); if (key === name) { return decodeURIComponent(value); // 注意解码！ } } return null; } const theme = getCookie('theme'); // ‘dark’

这里有一个关键细节：Cookie的值在存储时，如果包含特殊字符（如空格、中文），会被自动进行encodeURIComponent编码。因此，在读取时，你必须使用decodeURIComponent进行解码，否则你会得到像”%E6%9A%96%E7%94%B7”这样的乱码。很多初学者忘记这一步，导致数据处理出错。

3.2 写入/更新：一次只能设置一个

设置Cookie的语法是给document.cookie赋值一个符合Set-Cookie头格式的字符串。

// 设置一个简单的会话期Cookie document.cookie = ‘username=JohnDoe’; // 设置一个带过期时间和路径的Cookie const expiryDate = new Date(); expiryDate.setDate(expiryDate.getDate() + 7); // 7天后过期 document.cookie = `preference=dark_mode; expires=${expiryDate.toUTCString()}; path=/`; // 设置一个安全的HttpOnly Cookie（注意：HttpOnly无法通过JS设置！） // 以下写法是错误的，HttpOnly只能由服务器通过HTTP响应头设置。 // document.cookie = ‘sessionId=xyz789; Secure; HttpOnly’; // HttpOnly 无效

重要特性：document.cookie的赋值操作不会覆盖所有现有Cookie，它只会创建或更新你指定的那一个。这是它与普通对象赋值截然不同的地方。

document.cookie = ‘cookie1=value1’; document.cookie = ‘cookie2=value2’; console.log(document.cookie); // 输出：”cookie1=value1; cookie2=value2”

3.3 删除：巧用过期时间

JavaScript没有直接的deleteCookie方法。删除一个Cookie的标准做法是将其过期时间设置为一个过去的时间点。

function deleteCookie(name, path = ‘/’, domain = ‘’) { let cookieString = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=${path}`; if (domain) { cookieString += `; domain=${domain}`; } // 如果原Cookie设置了Secure，删除时最好也带上，确保能覆盖。 // cookieString += ‘; Secure’; document.cookie = cookieString; }

注意，删除时必须指定正确的path和domain，否则你可能无法删除掉目标Cookie，因为浏览器认为你要操作的是另一个不同作用域的Cookie。这是一个非常隐蔽的坑。

原生API的繁琐和易错催生了众多优秀的第三方库，其中最著名的就是js-cookie。

4. js-cookie库：现代化操作的优雅之选

js-cookie是一个轻量级（约800字节）、无依赖的库，它提供了极其简洁、直观且强大的API来操作Cookie，完全解决了原生API的痛点。

4.1 基础安装与使用

你可以通过npm安装，或直接使用CDN。

npm install js-cookie

// 在项目中引入 import Cookies from ‘js-cookie’; // 或者通过CDN // <script src=“https://cdn.jsdelivr.net/npm/js-cookie@3/dist/js.cookie.min.js”></script> // 此时 Cookies 作为全局变量可用

它的API设计得像操作一个普通对象：

// 设置Cookie Cookies.set(‘username’, ‘John Doe’); // 会话期Cookie Cookies.set(‘user_id’, ‘123’, { expires: 7 }); // 7天后过期 Cookies.set(‘preferences’, { theme: ‘dark’, lang: ‘zh’ }); // 自动序列化对象为JSON // 读取Cookie const username = Cookies.get(‘username’); // ‘John Doe’ const allCookies = Cookies.get(); // 获取所有Cookie，返回一个对象：{username: ‘John Doe’, user_id: ‘123’, …} const prefs = Cookies.get(‘preferences’); // ‘{“theme”:”dark”,”lang”:”zh”}’ // 注意：对于对象，get返回的是JSON字符串，通常需要配合JSON.parse使用，或者使用Cookies.getJSON() // 使用getJSON直接获取对象 const prefsObj = Cookies.getJSON(‘preferences’); // {theme: ‘dark’, lang: ‘zh’} // 删除Cookie Cookies.remove(‘username’); Cookies.remove(‘user_id’, { path: ‘/’, domain: ‘.example.com’ }); // 指定路径和域名删除

可以看到，js-cookie自动处理了值的编码解码（对于字符串），提供了便捷的对象序列化/反序列化，并且删除操作无需关心过期时间。

4.2 高级属性配置与转换器

js-cookie的强大之处在于它能以一致的方式处理所有Cookie属性。

// 设置一个包含所有属性的安全Cookie Cookies.set(‘session_token’, ‘encrypted_value_here’, { expires: 1/24, // 1小时，支持小数（天） path: ‘/admin’, domain: ‘.example.com’, secure: true, sameSite: ‘strict’ // 注意：HttpOnly 依然无法通过JS设置 }); // 使用转换器（Converter） // 假设后端设置的日期格式特殊，我们可以自定义读写逻辑 Cookies.withConverter({ read: function (value, name) { // 自定义读取时的解码逻辑 if (name === ‘special_date’) { return decodeMySpecialFormat(value); } return Cookies.converter.read(value, name); // 调用默认转换器 }, write: function (value, name) { // 自定义写入时的编码逻辑 if (name === ‘special_date’) { return encodeMySpecialFormat(value); } return Cookies.converter.write(value, name); } });

转换器功能在处理一些遗留系统或特殊编码需求时非常有用。

5. 实战场景与避坑指南

了解了工具，我们来看看在实际项目中如何运用，以及会遇到哪些“坑”。

5.1 场景一：用户偏好设置（主题、语言）

这是一个典型的前端主导的场景，Cookie的持久化特性很适合。

// 保存用户选择的主题 function saveUserTheme(themeName) { Cookies.set(‘app_theme’, themeName, { expires: 365, // 记住一年 path: ‘/’, sameSite: ‘lax’ }); // 同时可以立即应用主题 document.documentElement.setAttribute(‘data-theme’, themeName); } // 页面加载时读取并应用 function initTheme() { const savedTheme = Cookies.get(‘app_theme’) || ‘light’; // 默认亮色 document.documentElement.setAttribute(‘data-theme’, savedTheme); }

避坑点：如果网站有子域名（如app.example.com和blog.example.com），并且希望主题共享，则必须在设置Cookie时指定domain: ‘.example.com’。否则，每个子域名会有自己独立的主题Cookie。

5.2 场景二：与后端协同的认证令牌（Token）管理

这是Cookie最核心的用途之一。通常流程是：

1. 用户登录，后端验证成功后，在响应头中设置一个HttpOnly、Secure、SameSite=Lax的Cookie，里面包含加密的会话ID或JWT Token。
2. 前端无需任何操作，浏览器自动管理此Cookie的发送。
3. 前端需要实现“登出”功能时，可以调用一个后端API，由后端返回一个清除该Cookie的响应头，或者前端直接跳转到一个由后端处理的登出端点。

前端无法直接删除一个HttpOnly的Cookie！这是一个重要的安全限制。如果你的登出是纯前端操作，你需要让后端配合。一种常见做法是，前端发起一个到专门登出端点的请求（如POST /api/logout），后端在响应中设置一个同名的、立即过期的Cookie来覆盖它。

// 前端登出函数 async function logout() { try { await fetch(‘/api/logout’, { method: ‘POST’, credentials: ‘include’ }); // 登出成功后，清除前端可能存储的其他非HttpOnly状态 Cookies.remove(‘user_display_name’); // 跳转到登录页 window.location.href = ‘/login’; } catch (error) { console.error(‘Logout failed:’, error); } }

关键点：fetch请求必须设置credentials: ‘include’，浏览器才会携带跨域的Cookie（需要后端配置正确的CORS和Access-Control-Allow-Credentials）。

5.3 场景三：跨标签页/窗口通信

Cookie可以在同源的所有标签页间共享。利用这一点，可以实现简单的标签页状态同步。

// 标签页A：用户执行了某个动作 Cookies.set(‘global_notification’, ‘Data updated at ‘ + new Date().toISOString(), { path: ‘/’ }); // 标签页B：定时检查这个Cookie setInterval(() => { const notification = Cookies.get(‘global_notification’); if (notification && notification !== this.lastNotification) { this.lastNotification = notification; showToast(notification); // 可选：清除或更新Cookie，避免重复提示 // Cookies.remove(‘global_notification’); } }, 2000);

注意：这种方式比较原始，且有性能开销（轮询）。对于复杂的跨页通信，更推荐使用Broadcast Channel API或LocalStorage的storage事件。

5.4 常见“坑”与解决方案

1. Cookie大小限制：每个Cookie通常最大为4KB，每个域名下的Cookie总数也有限制（通常50个左右）。不要用Cookie存储大数据（如完整的用户配置对象）。大数据请存到LocalStorage，只在Cookie里放一个索引或版本号。
2. 编码问题：始终记得，原生API需要手动encodeURIComponent/decodeURIComponent，而js-cookie库默认帮你处理了字符串。但如果你存的是对象（通过JSON.stringify），取出来的是字符串，需要自己JSON.parse，或者直接用Cookies.getJSON。
3. 路径（Path）导致的“找不到”或“删不掉”：这是最常见的问题之一。如果你在/admin路径下设置了Path=/admin的Cookie，那么在根路径/下是读不到也删不掉它的。确保读写删除操作时的path属性一致。使用js-cookie时，如果不指定path，它默认为创建Cookie时的页面路径，这可能导致意外。最佳实践是，对于全局Cookie，显式设置path: ‘/’。
4. 域名（Domain）与子域名：不设置domain时，Cookie绑定到当前确切域名（如www.example.com），不会发给api.example.com。如果需要共享，需设置为.example.com（注意前面的点）。删除时也必须指定相同的domain。
5. Secure与HttpOnly的误解：Secure标志意味着Cookie只通过HTTPS传输。如果你的网站是HTTP，设置了Secure的Cookie将永远不会被发送。HttpOnly标志意味着JavaScript完全无法读写该Cookie，这是为了防御XSS攻击。你的会话Token必须是HttpOnly的，这通过前端JS无法实现，必须由后端设置。
6. SameSite的影响：现代浏览器（Chrome 80+）默认将未指定SameSite的Cookie视为Lax。这意味着来自其他站点的AJAX请求（如第三方API调用）默认不会携带你的Cookie。如果你的前端应用需要向另一个域名的后端API发送认证Cookie，后端必须显式设置SameSite=None; Secure。同时，前端的fetch或XMLHttpRequest需要设置withCredentials: true，并且后端必须配置正确的CORS响应头（Access-Control-Allow-Credentials: true和具体的Access-Control-Allow-Origin，不能是通配符*）。

6. Cookie的替代方案与选型思考

虽然Cookie很强大，但它并非万能。在新的Web API面前，我们需要根据场景做出选择。

• Web Storage (LocalStorage / SessionStorage)：

  • 优点：容量大（通常5-10MB），纯前端操作，API简单（setItem,getItem）。
  • 缺点：数据不会自动随HTTP请求发送，无法设置HttpOnly（易受XSS攻击），同源策略限制更严格。
  • 适用场景：存储不敏感的、大量的前端数据，如用户本地编辑的草稿、非关键的UI状态、缓存API响应数据等。

• IndexedDB：

  • 优点：容量极大（通常数百MB），支持事务、索引，可存储结构化数据甚至文件。
  • 缺点：API复杂异步，学习成本高。
  • 适用场景：需要在客户端存储大量结构化数据的离线应用、缓存大型资源（如图片、音频）。

• Cookie：

  • 优点：自动随请求发送（维持会话的关键），可设置HttpOnly和Secure（安全性高），可控制作用域（Domain/Path）和生命周期，有SameSite属性防御CSRF。
  • 缺点：容量小（4KB），每次请求都会携带增加带宽开销，API原始（需库辅助）。
  • 适用场景：用户身份认证（Session ID/JWT）、需要跟随请求的少量服务端状态、遵循SameSite规则的跨站/第三方集成。

选型黄金法则：

1. 凡是需要让服务器知道的信息，用Cookie（并且尽可能设为HttpOnly和Secure）。
2. 凡是不需要让服务器知道、但需要持久化或跨页的大数据，用LocalStorage。
3. 需要复杂查询或存储海量数据，考虑IndexedDB。
4. 临时性的会话数据，可以用SessionStorage（标签页关闭即消失）。

7. 安全最佳实践总结

操作Cookie时，安全必须放在首位：

1. 敏感Cookie必须标记为HttpOnly和Secure：这能有效抵御XSS攻击和中间人窃听。这意味着你无法用JavaScript读取它，这是好事，Token本就不该暴露给前端脚本。
2. 合理使用SameSite属性：对于认证Cookie，优先使用SameSite=Lax（默认）或Strict，这能粉碎大多数CSRF攻击。仅在确有必要且安全可控的情况下使用SameSite=None（并务必配合Secure）。
3. 避免在Cookie中存储敏感数据：即使有HttpOnly和Secure，也不要在Cookie中直接存储明文密码、个人身份证号等。应该存储一个由服务器生成的、随机且有时效性的令牌（Session ID或JWT）。
4. 设置合理的过期时间：为会话Cookie设置适当的过期时间，并考虑实现滑动过期或刷新令牌机制，平衡安全性与用户体验。
5. 防范Cookie篡改：对于重要的Cookie，服务器端应验证其签名或MAC（消息验证码），确保数据在客户端未被篡改。JWT就是一种自带签名验证的Token格式。
6. 注意Cookie的作用域：使用最严格的path和domain，不要随意设置为根路径或顶级域名，以减少攻击面。

掌握Cookie，不仅仅是记住几个API调用，更是理解Web状态管理、安全模型和前后端协作的基础。从原生的document.cookie到便捷的js-cookie库，从简单的键值对到复杂的属性配置，再到与各种安全策略的配合，希望这篇近万字的梳理能帮你建立起关于Cookie的完整知识图谱。在实际开发中，多思考“为什么用Cookie而不是别的”，多检查你设置的属性是否安全，这样才能写出既健壮又安全的Web应用。