js-cookie 安装与基础用法：set、get、remove 详解

在前端开发中，若直接使用原生 document.cookie 操作 Cookie，开发者必须自行拼接字符串、处理 URL 字符编解码并编写正则表达式来提取目标字段。这种手工操作不仅繁琐，而且极易由于作用域或过期时间格式书写失误引发静默 Bug。轻量级库 js-cookie 提供了结构清晰、语义直观的接口封装，体积压缩后仅约 2KB。本文将直接从其安装步骤切入，深入剖析 set、get 与 remove 三个核心 API 的标准用法、常用配置项与关键排错细节。

一、js-cookie 的安装与模块引入

假设项目正在采用现代打包工具（如 Vite、Webpack）或传统的服务端渲染多页应用，引入 js-cookie 主要有两种标准途径：通过包管理器安装模块，或通过 CDN 直接引入脚本文件。

1. 使用包管理器安装

在工程根目录下打开终端，根据项目使用的包管理工具执行以下命令：

# 使用 npm
npm install js-cookie

# 使用 yarn
yarn add js-cookie

# 使用 pnpm
pnpm add js-cookie

在 js-cookie 3.x 版本中，库本身已经内置了 TypeScript 类型定义文件，无需再手动安装 @types/js-cookie。完成安装后，在业务代码或模块文件中引入全局对象：

// ES Module 语法引入
import Cookies from 'js-cookie';

// CommonJS 规范引入（Node/SSR 环境）
const Cookies = require('js-cookie');

2. 使用 CDN 外部链接直接引入

对于不需要前端构建工具的传统静态页面或快速原型验证，可直接在 HTML 文件的 <head> 或 <body> 底部加入 CDN 链接：

<!-- 引入特定主版本的压缩包 -->
<script src="https://cdn.jsdelivr.net/npm/js-cookie@3/dist/js.cookie.min.js"></script>
<script>
  // 引入后全局挂载 window.Cookies
  Cookies.set('welcome_tip', 'seen');
</script>

二、Cookies.set() 详解：写入与作用域配置

Cookies.set(name, value, [options]) 是将键值对存入浏览器 Cookie 的基础方法。它的前两个参数分别为键名与键值（字符串格式），第三个参数为可选的配置对象。

1. 基础调用与默认生命周期

当省略第三个配置参数时，所创建的 Cookie 默认属于会话 Cookie（Session Cookie）。这类 Cookie 在用户关闭当前浏览器标签页或会话结束时会被浏览器自动清理。

// 创建一个基础会话 Cookie
Cookies.set('theme', 'dark');

2. 设置有效期（expires）

有效期支持直接传入整数或浮点数（以“天”为单位），也支持直接传入 JavaScript 的 Date 对象以指定绝对时间戳：

// 方式一：设置 7 天后失效
Cookies.set('user_id', '9527', { expires: 7 });

// 方式二：设置半天（12 小时）后失效
Cookies.set('temp_code', 'AB82', { expires: 0.5 });

// 方式三：传入指定日期对象
const expireDate = new Date();
expireDate.setTime(expireDate.getTime() + 60 * 60 * 1000); // 1 小时后
Cookies.set('session_token', 'xyz_123', { expires: expireDate });

3. 路径（path）与域名（domain）

如果不显式指定 path，浏览器默认将 Cookie 绑定在当前页面所在的路径层级（例如在 /dashboard/analytics 下写入，则默认为该路径及其子路径可见）。通常为了使全站各路由页面均可读取同一个凭据，强烈建议显式声明 path: '/'。

// 作用于整站所有页面
Cookies.set('locale', 'zh-CN', { path: '/' });

// 作用于特定顶级域名与所有子域名（如 a.example.com 与 b.example.com 共享）
Cookies.set('sso_token', 'jwt_val', { domain: 'example.com', path: '/' });

4. 安全标识：secure 与 sameSite

在涉及敏感凭证或跨站请求时，安全属性是不可忽略的配置项：

• secure: true：强制要求该 Cookie 仅能在 HTTPS 安全加密协议下通过网络传输，避免明文泄露。
• sameSite：限制跨站请求携带 Cookie 的策略，可选值为 'strict'、'lax' 或 'none'。在大部分应用中，设为 'lax' 或 'strict' 能有效防御 CSRF 攻击。若设置 sameSite: 'none'，则必须同时开启 secure: true。

// 生产环境安全配置示例
Cookies.set('auth_token', 'secret_abc', {
  expires: 14,
  path: '/',
  secure: true,
  sameSite: 'lax'
});

三、Cookies.get() 详解：精准读取与全量读取

Cookies.get() 专门用于读取当前页面权限范围内可见的 Cookie。与原生字符串解析相比，它内置了解码逻辑，若目标键不存在则返回统一的 undefined，不会导致脚本报错。

1. 读取单个指定 Cookie

向方法传入键名字符串作为参数，如果存在对应记录，返回解码后的文本字符串；如果该 Cookie 不存在或已过期，则直接返回 undefined：

// 读取指定键
const theme = Cookies.get('theme');
console.log(theme); // 输出: "dark" 或 undefined

// 安全判断
if (Cookies.get('auth_token')) {
  // 执行已登录逻辑
} else {
  // 执行登录重定向
}

2. 获取当前可见的所有 Cookie

当调用 Cookies.get() 时不传入任何参数，它会遍历 document.cookie 中当前上下文能获取到的所有项目，将其整合成一个键值对应的 JavaScript 纯对象（Object）返回：

// 获取全部 Cookie 对象
const allCookies = Cookies.get();
console.log(allCookies);
// 输出示例: { theme: "dark", locale: "zh-CN", user_id: "9527" }

3. 解析 JSON 结构数据的通用模式

由于存储时将对象序列化成了 JSON 字符串，在读取后需要结合 JSON.parse 还原，建议使用 try...catch 或降级兜底防止解析异常：

// 安全读取并解析 JSON Cookie
function getParsedCookie(key) {
  const rawValue = Cookies.get(key);
  if (!rawValue) return null;
  try {
    return JSON.parse(rawValue);
  } catch (err) {
    console.warn(`Cookie [${key}] 解析为 JSON 失败:`, err);
    return null;
  }
}

// 使用示例
const userProfile = getParsedCookie('user_profile');

四、Cookies.remove() 详解：安全删除与常见失效排查

Cookies.remove(name, [options]) 的功能是使指定的 Cookie 立即失效并从浏览器中清除。它的底层机制是将该 Cookie 的过期时间重设为一个早已过去的格林威治时间（Epoch Time）。

1. 基础删除

如果 Cookie 在创建时没有附加特殊的 path 或 domain，直接传入键名即可完成清理：

// 删除当前路径下的默认 Cookie
Cookies.remove('theme');

2. 携带作用域参数精准删除

在清理任何全局或共享 Cookie 时，应始终附加与写入时相同的 path 和 domain 属性：

// 错误示范：无法删除根路径下的全局 Cookie
Cookies.remove('auth_token');

// 正确示范：补齐写入时所用的 path
Cookies.remove('auth_token', { path: '/' });

// 若写入时带有 domain，删除时同样必须完整注明
Cookies.remove('sso_token', { path: '/', domain: 'example.com' });

五、重要限制与安全边界

在使用 js-cookie 时，需要明确前端脚本操作 Cookie 的固有能力边界：

• 无法操作 HttpOnly 标识的 Cookie：服务端在响应头 Set-Cookie 中若附加了 HttpOnly，浏览器会严格禁止任何 JavaScript 脚本（包括 js-cookie）读取或修改该项。这是防范 XSS 劫持敏感凭据的标准安全措施。
• 单项容量与总数限制：单个 Cookie 的数据体积（包含键名与键值）最大通常不能超过 4KB。如果存储超长数据，超出的部分将被浏览器截断或丢弃。大数据量状态管理请选用 localStorage 或 IndexedDB。
• 同名同路径覆盖规则：在相同的 path 与 domain 下重复调用 Cookies.set() 会直接覆盖旧值；但如果 path 不同，浏览器会将其视为两条平行的独立 Cookie，这常会导致读取逻辑混乱。

六、基础 API 速查与总结

为了便于实际开发中快速查阅，下表汇总了 js-cookie 核心 API 的参数、默认值及典型使用场景：

方法声明	参数说明	返回值	典型应用场景
Cookies.set(key, val, [opt])	key: 键名 val: 字符串 opt: expires/path/domain/secure/sameSite	写入成功的 Cookie 原始字符串	持久化用户偏好（主题/语言）、存储登录会话凭据
Cookies.get(key)	key: 目标键名（字符串）	对应字符串或 undefined	路由守卫鉴权、恢复前端用户状态
Cookies.get()	无参数	包含所有可见键值的 Plain Object	全量调试、迁移存储或批量检查状态
Cookies.remove(key, [opt])	key: 目标键名 opt: path 与 domain（须匹配）	undefined	退出登录、清理过期业务缓存