JavaScript怎么读取Cookie：document.cookie基础用法与格式解析

一、document.cookie 基础表现与格式特征

在浏览器的控制台或脚本中，获取当前页面的 Cookie 非常直接，只需读取 document.cookie 即可：

// 读取当前作用域下的全部可见 Cookie
const cookieStr = document.cookie;
console.log(cookieStr);
// 输出示例："username=zhangsan; theme=dark; session_token=ab12cd34"

观察其输出内容，可以归纳出 document.cookie 字符串的四个核心格式特征：

• 分号加空格分隔：不同的 Cookie 之间统一使用一个分号和一个英文空格（; ）连接。
• 名值对结构：每一项都遵循 名称=值（key=value）的形式。
• 只暴露键值：即便在设置 Cookie 时配置了 expires、max-age、path、domain、sameSite 或 secure，这些属性均不会在读取时出现，document.cookie 仅返回键名和键值。
• 缺失即为空串：如果当前页面没有任何可访问的 Cookie，返回的是一个长度为 0 的空字符串 ""，而不是 null 或 undefined。

二、为什么有些 Cookie 在 document.cookie 中读不到？

在排查 Cookie 读取问题时，经常有开发者发现某些在浏览器控制台 Application/Storage 面板中明确存在的 Cookie，通过 document.cookie 却读不出来。这通常由以下两个核心机制决定：

1. HttpOnly 安全标记

如果在设置 Cookie 时附加了 HttpOnly 标志（常见于用户鉴权凭证、Session ID），浏览器会严格阻止任何客户端脚本（包括 JavaScript）访问该 Cookie。这是一种关键的安全防御机制，旨在降低跨站脚本攻击（XSS）发生时攻击者直接窃取用户身份凭证的风险。

2. 域名（Domain）与路径（Path）隔离

Cookie 具有明确的作用域约束。只有当前页面的 URL 同时匹配 Cookie 的 Domain 和 Path 时，该 Cookie 才会出现在 document.cookie 中。

• 如果 Cookie 的 Path 设为 /admin，那么在 /blog 页面中执行 JavaScript 是读不到该 Cookie 的。
• 如果 Cookie 的 Domain 设为特定子域 api.example.com，且未共享给父域，那么在 web.example.com 下也无法读取。

三、将 document.cookie 解析为对象的完整步骤

为了在业务逻辑中按名称快速获取某个 Cookie 的值，直接操作纯文本字符串非常低效且容易出错。规范的做法是在读取时将其解析为一个标准的 JavaScript 键值对象。

直接使用 split(';') 往往潜藏边界缺陷。一个健壮的解析过程必须处理以下几点：

1. 空串防御：当 document.cookie 为空时，split(';') 会产生包含一个空字符串的单元素数组 [""]，必须前置拦截。
2. 首尾空白剔除：各条目间以分号和空格隔开，直接切分会导致后续项键名前带有空格，必须使用 trim()。
3. 值内包含等号：某些 Token 或 Base64 字符串的值末尾包含 =。若采用 item.split('=') 切分，值会被切碎。应找到第一个 = 的索引，并以此切分为键与值。
4. URL 编解码：Cookie 的标准规范建议使用 encodeURIComponent 对非 ASCII 字符或保留字符进行编码，读取时必须对应使用 decodeURIComponent 解码。

代码实现：封装 parseCookies 与 getCookie

根据上述逻辑，可以编写出两款使用率最高的实用函数：

/**
 * 将当前页面的 document.cookie 完整解析为键值对象
 * @returns {Record<string, string>}
 */
function getAllCookies() {
  const cookieObj = {};
  const rawCookie = document.cookie;

  // 1. 处理空字符串情况
  if (!rawCookie || rawCookie.trim() === '') {
    return cookieObj;
  }

  // 2. 按分号拆分为单项
  const items = rawCookie.split(';');

  for (let i = 0; i < items.length; i++) {
    // 3. 去除首尾空格
    const item = items[i].trim();
    if (!item) continue;

    // 4. 定位第一个等号的位置
    const equalIndex = item.indexOf('=');
    if (equalIndex === -1) {
      // 存在只有键没有等号的非规范情况
      try {
        const key = decodeURIComponent(item);
        cookieObj[key] = '';
      } catch (e) {
        cookieObj[item] = '';
      }
      continue;
    }

    const rawKey = item.slice(0, equalIndex);
    const rawVal = item.slice(equalIndex + 1);

    // 5. 进行 URI 解码并写入对象
    try {
      const key = decodeURIComponent(rawKey);
      const val = decodeURIComponent(rawVal);
      cookieObj[key] = val;
    } catch (e) {
      // 若解码异常（如非法字符），回退使用原始字符串
      cookieObj[rawKey] = rawVal;
    }
  }

  return cookieObj;
}

/**
 * 根据指定名称精准获取单个 Cookie 值
 * @param {string} name 目标 Cookie 名称
 * @returns {string | null}
 */
function getCookie(name) {
  if (!name) return null;
  const cookies = getAllCookies();
  return Object.prototype.hasOwnProperty.call(cookies, name) ? cookies[name] : null;
}

四、现代浏览器新方案：异步 Cookie Store API

长期以来，document.cookie 都是一个同步属性，在大型应用或存在大量 Cookie 的情况下，频繁同步读取可能会轻微阻塞主线程渲染。现代浏览器逐步引入了异步的 Cookie Store API（挂载于 window.cookieStore）。

// 检查当前浏览器是否支持 Cookie Store API
if ('cookieStore' in window) {
  // 异步获取指定 Cookie
  window.cookieStore.get('username')
    .then(cookie => {
      if (cookie) {
        console.log('读取成功:', cookie.name, cookie.value);
      } else {
        console.log('未找到该 Cookie');
      }
    })
    .catch(err => console.error('读取出错:', err));
} else {
  // 不支持时回退使用传统的 document.cookie 解析方案
  console.log('回退方案:', getCookie('username'));
}

需要注意，Cookie Store API 目前仅在 Chrome、Edge 等 Chromium 内核的现代浏览器中得到良好支持，且必须运行在 HTTPS 安全上下文或 localhost 下。Safari 和部分老旧浏览器尚未完全兼容，因此传统的 document.cookie 依然是全平台通用的基石方案。

五、常见问题与核心要点总结

掌握 document.cookie 的格式特征与限制边界，是编写稳定前端数据存取逻辑的基础。通过标准化的切分与解码封装，可以在保障数据完整性的同时，避免各类因字符串排版和作用域掩蔽引起的疑难问题。