js-cookie 是一个专为浏览器环境设计的轻量级 JavaScript API，用于简化 Cookie 的创建、读取与删除操作。它不仅支持 ES 模块、CommonJS 和 AMD，还强调对现代浏览器的兼容性，以及依照 RFC 6265 规范进行编码处理。
该库无依赖、体积小（压缩后 < 800 字节），适用于各种前端项目，用来代替手写 document.cookie 时容易出错的繁琐逻辑。
为何选用 js-cookie
在传统的浏览器 Cookie 操作中，你常常需要拼接字符串设置属性、处理编码、手动管理路径、域、失效时间等细节。js-cookie 对这些常见出错点提供了封装：
- 自动处理 Cookie 名称和值的编码、解码。
- 简化“设置 expires、path、domain、secure、sameSite”这些属性的使用。
- 提供统一接口
Cookies.set()、Cookies.get()、Cookies.remove()，让代码更清晰。 - 支持全局默认属性配置，也允许按调用覆盖。
用它能减少 Cookie 操作中的重复代码和潜在 bug，提高前端项目的稳定性。
安装与引入方式
在具体项目中，你可以通过以下方式引入 js-cookie：
若使用 npm/yarn 管理依赖，可执行：
npm install js-cookie若在纯浏览器环境使用 CDN，可直接通过 <script> 标记引入 UMD 版本。
引入后，如果是模块环境，可写：
import Cookies from 'js-cookie';在 CommonJS 环境则为：
const Cookies = require('js-cookie');做好引入后，便可使用 Cookies 对象进行后续操作。
基本用法详解
1. 设置 Cookie
你可以用最简单的方式设置一个 Cookie，例如：
Cookies.set('name', 'value');
以上代码将在当前域下、路径为默认（/）的位置写入名为 name、值为 value 的 session Cookie（浏览器关闭即失效）。
如果想让它保存更长时间，比如 7 天：
Cookies.set('name', 'value', { expires: 7 });
你也可以设置路径、域、是否安全（https）、同站策略（sameSite）等：
Cookies.set('name', 'value', { expires: 7, path: '/', domain: '.example.com', secure: true, sameSite: 'strict' });
2. 读取 Cookie
读取单个值：
const val = Cookies.get('name');
如果 name 不存在，则返回 undefined。
你也可以拿到当前可见所有 Cookie 的键值对：
const all = Cookies.get();
// all 是一个对象，例如 { name: 'value', foo: 'bar' }
3. 删除 Cookie
简单删除：
Cookies.remove('name');
但如果在设置时用了特定 path 或 domain，那么删除时也必须匹配这些属性，否则可能删除失败。例如：
Cookies.set('name', 'value', { path: '/app' });
// 此时删除必须：
Cookies.remove('name', { path: '/app' });
否则删除操作不会如你所愿。
进阶功能和注意事项
全局默认属性
如果你在一个应用里，几乎所有 Cookie 都用相同的 domain 或 path，那么可以用 withAttributes() 方法创建一个定制版 API：
const api = Cookies.withAttributes({ path: '/', domain: '.example.com' });
api.set('name', 'value');
这样后续调用就不用每次都传 { path, domain } 了。
编码／解码策略
默认情况下，js-cookie 会对 Cookie 名称和值中不合法字符进行 percent-encoding 处理，使其遵守 RFC 6265。
如果你有自定义的编码或解码需求（如特殊字符、非 UTF-8 编码等），库也提供了 withConverter() 方法，可自定义读取或写入时的转换逻辑。
命名空间冲突处理
若你的页面环境中已有其他名为 Cookies 的对象（例如第三方脚本、SDK 插件），为了避免冲突，js-cookie 提供 noConflict() 方法，允许你将其 API 赋值给新的变量，而恢复或保留原有 window.Cookies。
注意浏览器行为与安全问题
- 虽然设置 path/domain 等属性很方便，但浏览器对于不同域、子域或文件路径（尤其 IE）可能有兼容差异，需谨慎测试。
- 若设置了
secure: true，Cookie 只会在 HTTPS 连接下传输；若忘记配置，而在 HTTPS 环境下期望被发送，可能出现问题。 - 因为 Cookie 是常被用于追踪或状态维持的机制，注意同站／跨站策略（sameSite）及 XSS、防 CSRF 相关的安全考量。
- 不要依赖 Cookie 存储极大数据——浏览器对单 Cookie 长度或域下总 Cookie 数量都有内置限制。
典型使用场景
在你的网站或 Web 应用中，可能会用到如下情况：
- 用户登录状态标记：登录成功后生成一个标志 Cookie，设置合理的 expires，并在退出或超时时删除。
- 页面偏好设置：如是否开启暗模式、语言选择等，可以使用 Cookie 保存，页面刷新或下次访问时读取并应用。
- 简易追踪／记忆行为：如“下次不再提示”之类的标志，也可用 Cookie 实现。
在这些场景里，借助 js-cookie 的接口，你可以把代码搞得更整洁、更可维护。
总结
总而言之，js-cookie 是一个非常实用的浏览器端 Cookie 操作库。它用极简的 API 为前端开发者屏蔽了很多繁琐细节，让你更专注于业务逻辑而不是 Cookie 的实现细节。在项目中合理使用它，可以提升代码可读性、减少错误、提升用户体验。如果你正在开发前端项目、或者希望快速、稳定地管理浏览器端 Cookie，那么值得将 js-cookie 纳入你的工具箱。