怎么用 js-cookie 设置 Cookie 过期时间和作用域路径

在使用 js-cookie 写入浏览器 Cookie 时，设置过期时间与作用域路径是通过 Cookies.set() 方法的第三个参数（属性配置对象）完成的。通过配置 expires 属性，可以指定 Cookie 的保留天数或具体失效时间点（若不提供则默认为会话 Cookie，关闭浏览器即清除）；通过配置 path 属性，可以指定哪些 URL 路径能够读取该 Cookie（通常推荐设置为 path: '/'，使全站所有页面共享该数据）。掌握这两个配置的传参规则与浏览器的底层继承机制，是解决前端存储“跨页面读不到”和“过期时间不生效”等高频问题的关键。

一、核心语法与底层映射机制

js-cookie 对原生 document.cookie 繁琐的字符串拼接进行了标准化封装。当调用 Cookies.set(key, value, attributes) 时，传入的对象属性会自动转换为符合 RFC 6265 规范的标准 HTTP Cookie 格式。

最常见的基础调用语法如下：

// 引入 js-cookie 后调用
Cookies.set('user_token', 'abc123xyz', {
  expires: 7, // 7 天后过期
  path: '/'   // 根路径，整站所有路由均可访问
});

上述代码执行后，js-cookie 会在底层将天数转换为对应的 GMT 国际标准时间戳，并拼接成 user_token=abc123xyz; Expires=Sat, 07 Nov 2026 14:00:00 GMT; Path=/ 写入浏览器存储系统。

二、详细设置 Cookie 过期时间（expires 参数）

在 js-cookie 中，expires 参数支持两种传值形式：数值型天数与 JavaScript Date 对象。不同的赋值方式适用于不同的业务场景。

1. 设置相对天数（整数或浮点数）

直接传入一个正数，代表该 Cookie 从当前时间起可以保存的自然天数（按每天 24 小时计算）。

// 示例 1：设置保留 30 天的登录凭证
Cookies.set('auth_token', '9a8b7c6d', { expires: 30, path: '/' });

// 示例 2：设置保留半天（12 小时）的临时状态
// 0.5 天即 12 小时，0.25 天即 6 小时
Cookies.set('promo_banner_closed', 'true', { expires: 0.5, path: '/' });

2. 传入 Date 对象（精确到时分秒）

若需要设置更精细的过期时效（例如 15 分钟、2 小时，或是当天的 23:59:59），可以构造一个精确的 Date 实例传入 expires：

// 示例 3：设置 30 分钟后过期的手机验证码
const expireTime = new Date(Date.now() + 30 * 60 * 1000); // 当前时间向后推 30 分钟
Cookies.set('sms_code', '682194', {
  expires: expireTime,
  path: '/'
});

// 示例 4：设置在明天凌晨 0 点准时过期的签到状态
const midnight = new Date();
midnight.setDate(midnight.getDate() + 1);
midnight.setHours(0, 0, 0, 0);

Cookies.set('daily_checkin', 'done', {
  expires: midnight,
  path: '/'
});

3. 不设置 expires（会话级别 Cookie）

如果忽略 expires 属性，该 Cookie 会被浏览器识别为会话（Session）Cookie。它仅保存在内存中，当用户彻底关闭浏览器窗口进程后，浏览器会自动将其清除。

// 会话 Cookie：浏览器关闭后自动消失
Cookies.set('temp_session_id', 'sess_44102', { path: '/' });

三、全流程操作步骤与环境配置

要在实际项目中完整落地 js-cookie 的配置，可以按照以下标准步骤执行操作与验证：

步骤 1：安装与引入依赖

根据前端项目的构建工具链选择合适的引入方式：

# 在现代前端项目（Vue / React / Vite / Webpack）中安装：
npm install js-cookie

在代码中按需导入：

import Cookies from 'js-cookie';

若在无需打包工具的轻量 HTML 页面中使用，可通过 CDN 引入脚本：

<!-- CDN 引入示例 -->
<script src="https://cdn.jsdelivr.net/npm/js-cookie@3.0.5/dist/js.cookie.min.js"></script>
<script>
  // 全局变量 window.Cookies 已就绪
  console.log(typeof Cookies.get); // 输出 "function"
</script>

步骤 2：组合调用 set 方法

明确业务数据的保留时长与访问目录，在业务逻辑中执行存储：

// 写入用户偏好语言，保存 365 天，全站可见
Cookies.set('user_lang', 'zh-CN', {
  expires: 365,
  path: '/'
});

四、设置作用域路径（path 参数）与可访问性规则

Cookie 的 path 属性定义了哪些 URL 路径可以向服务器发送该 Cookie，或者在前端通过 Cookies.get() 读取该 Cookie。

1. 为什么推荐显式设置 path: '/'

在默认情况下，如果写入 Cookie 时没有指定 path，浏览器会将当前页面所在的目录路径作为默认值。例如，如果用户在 https://example.com/order/list 页面执行了 Cookies.set('step', '1')，该 Cookie 的 path 会被隐式设置为 /order。

这将导致严重的隐蔽问题：当用户跳转到 https://example.com/profile 或者首页 https://example.com/ 时，调用 Cookies.get('step') 会返回 undefined，因为父级路径或同级其他目录无法读取属于 /order 路径的 Cookie。因此，绝大多数业务场景下，均应显式传入 path: '/'，确保整站数据一致可用。

2. 单向继承与隔离规则

Cookie 的路径访问遵循单向向下继承机制：

• 父级对子级开放：在 path: '/' 设置的 Cookie，对 /、/shop、/admin 等整站所有子路由都可见。
• 子级对父级隔离：在 path: '/admin' 设置的 Cookie，只能在 /admin 及其子路径（如 /admin/dashboard）下读取，根路径 / 无法读取。

// 业务隔离示例：后台管理专有 Cookie
// 此时在前台页面访问无法读取该 Cookie，降低信息暴露风险
Cookies.set('admin_panel_layout', 'dense', {
  expires: 14,
  path: '/admin'
});

五、浏览器开发者工具验证与避坑指南

完成代码编写后，必须在浏览器中验证设置是否真正生效。

1. 在 Chrome / Edge 开发者工具中核验

1. 在网页中按 F12 或右键选择“检查”打开开发者工具。
2. 切换到顶部的 Application（应用程序）选项卡。
3. 在左侧导航栏展开 Storage -> Cookies，点击当前站点的域名。
4. 在右侧表格中查找刚才写入的键名，重点核对以下两列：
   • Expires / Max-Age：若传入了天数或 Date，应显示具体的年月日时分秒（UTC 时间）；若未指定，则应显示为 Session。
   • Path：确认显示的是 / 还是特定子目录。

2. 最容易踩坑的删除与覆盖陷阱

当 Cookie 创建时指定了特定路径（例如 path: '/'），在删除或修改该 Cookie 时，必须传入完全相同的 path 参数。如果不传入，Cookies.remove 会尝试以当前页面的默认路径去删除，导致浏览器找不到对应项，删除操作静默失败：

// 错误做法：创建时指定了 path，删除时未指定
Cookies.set('user_id', '10086', { expires: 7, path: '/' });
Cookies.remove('user_id'); // ✘ 无法成功删除！

// 正确做法：必须显式传入创建时相同的 path 配置
Cookies.remove('user_id', { path: '/' }); // ✔ 成功删除！

同理，如果不小心在不同的页面用不同的 path 写入了同名的键，浏览器中会同时存在两条 user_id 记录（例如一条 Path 为 /，另一条 Path 为 /goods），导致读取时出现难以排查的值混乱。始终统一使用 path: '/' 能彻底规避这一问题。

六、快速参考对照表