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与CookieCookie的旅程始于服务器的一个响应。当服务器决定要给客户端设置一个Cookie时它会在HTTP响应头中添加一个Set-Cookie字段。这个字段的格式包含了键值对以及一系列控制属性。HTTP/1.1 200 OK Content-Type: text/html Set-Cookie: sessionIdabc123; ExpiresWed, 21 Oct 2026 07:28:00 GMT; Path/; Secure; HttpOnly浏览器接收到这个响应后会按照指令将sessionIdabc123这个键值对以及相关的属性过期时间、路径、安全标志等存储起来。之后每当浏览器向同一域名、符合路径规则的地址发起请求时都会自动在请求头中带上这个Cookie。GET /user/profile HTTP/1.1 Host: www.example.com Cookie: sessionIdabc123; themedark这就是为什么Cookie能维持登录状态——服务器在登录成功后设置一个包含用户身份的Cookie浏览器后续的所有请求都会自动“出示”这个身份凭证。而LocalStorage则完全不具备这个“自动携带”的特性它只是一个纯粹的前端沙箱。2.2 核心属性详解控制Cookie行为的开关仅仅一个键值对是远远不够的。Cookie的强大和复杂都体现在它的一系列属性上。这些属性决定了Cookie何时生效、在哪里生效、以及如何被访问。Expires/Max-Age生命周期控制器Expires指定一个具体的GMT格式的过期时间点。例如ExpiresWed, 21 Oct 2026 07:28:00 GMT。时间不准确或格式错误会导致Cookie立即失效这是新手常踩的坑。Max-Age指定从现在开始Cookie存在的秒数优先级高于Expires。例如Max-Age259200030天。设置为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); // 输出”sessionIdabc123; themedark; userId42”你会发现它返回的是一个由分号和空格拼接的字符串而不是一个方便操作的对象。你需要手动解析它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 ‘usernameJohnDoe’; // 设置一个带过期时间和路径的Cookie const expiryDate new Date(); expiryDate.setDate(expiryDate.getDate() 7); // 7天后过期 document.cookie preferencedark_mode; expires${expiryDate.toUTCString()}; path/; // 设置一个安全的HttpOnly Cookie注意HttpOnly无法通过JS设置 // 以下写法是错误的HttpOnly只能由服务器通过HTTP响应头设置。 // document.cookie ‘sessionIdxyz789; Secure; HttpOnly’; // HttpOnly 无效重要特性document.cookie的赋值操作不会覆盖所有现有Cookie它只会创建或更新你指定的那一个。这是它与普通对象赋值截然不同的地方。document.cookie ‘cookie1value1’; document.cookie ‘cookie2value2’; console.log(document.cookie); // 输出”cookie1value1; cookie2value2”3.3 删除巧用过期时间JavaScript没有直接的deleteCookie方法。删除一个Cookie的标准做法是将其过期时间设置为一个过去的时间点。function deleteCookie(name, path ‘/’, domain ‘’) { let cookieString ${name}; expiresThu, 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-cookie3/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最核心的用途之一。通常流程是用户登录后端验证成功后在响应头中设置一个HttpOnly、Secure、SameSiteLax的Cookie里面包含加密的会话ID或JWT Token。前端无需任何操作浏览器自动管理此Cookie的发送。前端需要实现“登出”功能时可以调用一个后端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 常见“坑”与解决方案Cookie大小限制每个Cookie通常最大为4KB每个域名下的Cookie总数也有限制通常50个左右。不要用Cookie存储大数据如完整的用户配置对象。大数据请存到LocalStorage只在Cookie里放一个索引或版本号。编码问题始终记得原生API需要手动encodeURIComponent/decodeURIComponent而js-cookie库默认帮你处理了字符串。但如果你存的是对象通过JSON.stringify取出来的是字符串需要自己JSON.parse或者直接用Cookies.getJSON。路径Path导致的“找不到”或“删不掉”这是最常见的问题之一。如果你在/admin路径下设置了Path/admin的Cookie那么在根路径/下是读不到也删不掉它的。确保读写删除操作时的path属性一致。使用js-cookie时如果不指定path它默认为创建Cookie时的页面路径这可能导致意外。最佳实践是对于全局Cookie显式设置path: ‘/’。域名Domain与子域名不设置domain时Cookie绑定到当前确切域名如www.example.com不会发给api.example.com。如果需要共享需设置为.example.com注意前面的点。删除时也必须指定相同的domain。Secure与HttpOnly的误解Secure标志意味着Cookie只通过HTTPS传输。如果你的网站是HTTP设置了Secure的Cookie将永远不会被发送。HttpOnly标志意味着JavaScript完全无法读写该Cookie这是为了防御XSS攻击。你的会话Token必须是HttpOnly的这通过前端JS无法实现必须由后端设置。SameSite的影响现代浏览器Chrome 80默认将未指定SameSite的Cookie视为Lax。这意味着来自其他站点的AJAX请求如第三方API调用默认不会携带你的Cookie。如果你的前端应用需要向另一个域名的后端API发送认证Cookie后端必须显式设置SameSiteNone; 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规则的跨站/第三方集成。选型黄金法则凡是需要让服务器知道的信息用Cookie并且尽可能设为HttpOnly和Secure。凡是不需要让服务器知道、但需要持久化或跨页的大数据用LocalStorage。需要复杂查询或存储海量数据考虑IndexedDB。临时性的会话数据可以用SessionStorage标签页关闭即消失。7. 安全最佳实践总结操作Cookie时安全必须放在首位敏感Cookie必须标记为HttpOnly和Secure这能有效抵御XSS攻击和中间人窃听。这意味着你无法用JavaScript读取它这是好事Token本就不该暴露给前端脚本。合理使用SameSite属性对于认证Cookie优先使用SameSiteLax默认或Strict这能粉碎大多数CSRF攻击。仅在确有必要且安全可控的情况下使用SameSiteNone并务必配合Secure。避免在Cookie中存储敏感数据即使有HttpOnly和Secure也不要在Cookie中直接存储明文密码、个人身份证号等。应该存储一个由服务器生成的、随机且有时效性的令牌Session ID或JWT。设置合理的过期时间为会话Cookie设置适当的过期时间并考虑实现滑动过期或刷新令牌机制平衡安全性与用户体验。防范Cookie篡改对于重要的Cookie服务器端应验证其签名或MAC消息验证码确保数据在客户端未被篡改。JWT就是一种自带签名验证的Token格式。注意Cookie的作用域使用最严格的path和domain不要随意设置为根路径或顶级域名以减少攻击面。掌握Cookie不仅仅是记住几个API调用更是理解Web状态管理、安全模型和前后端协作的基础。从原生的document.cookie到便捷的js-cookie库从简单的键值对到复杂的属性配置再到与各种安全策略的配合希望这篇近万字的梳理能帮你建立起关于Cookie的完整知识图谱。在实际开发中多思考“为什么用Cookie而不是别的”多检查你设置的属性是否安全这样才能写出既健壮又安全的Web应用。