HarmonyOS 7 ArkWeb fetchCookie 为什么漏掉分区 Cookie？API 26 两个参数别传反

登录页明明能正常访问，应用侧调用 fetchCookie 却读不到预期项，容易先怀疑“Cookie 被清了”。在 HarmonyOS 7 / API 26，先看两件更具体的事：你读的是普通窗口还是无痕窗口的存储空间？你是否要求把第一方分区 Cookie 包含在返回结果里？这是两个独立的参数，少检查一个都可能误判。

版本边界先说清

华为 2026-09-04 更新的 ArkWeb API 26 差异表列出了两个签名：fetchCookieSync(url, incognito?, includePartitionedCookies?)，以及返回 Promise<string> 的 fetchCookie(url, incognito, includePartitionedCookies)。旧的 fetchCookie(url, callback) 仍是另一个重载，不能把回调参数误当成无痕标志。下文针对 API 26；旧 SDK 编译不了新重载时，先核对 SDK 与设备版本，而不是把它当成运行时丢 Cookie。

incognito 用来选择读取哪个浏览模式的 Cookie 存储空间；includePartitionedCookies 决定读取时是否包含第一方分区 Cookie。后者不是允许第三方 Cookie 的开关，也不会凭空生成服务端没有设置的 Cookie。正常/无痕、本分区/非分区是两个不同维度。

案例一：页面有会话，读取时漏了分区项

复现前提要明确：测试站点确实设置了符合条件的第一方分区 Cookie，而且在同一个 URL 和同一个浏览模式下对照读取。若服务端没有设置该类 Cookie，切换参数后两次结果相同是正常的，不能据此说新参数失效。

先用 false 读取，再仅把第三个参数改为 true。如果第二次才包含目标项，问题就落在读取范围；如果都没有，就继续检查完整 URL、Cookie 的域、路径、有效期和服务端下发条件。不要为了排查在日志中打印真实会话值，只记录目标项是否存在及两次结果是否不同。

import { webview } from '@kit.ArkWeb';

const url = 'https://example.com/account'; // 用实际测试页的完整 HTTPS URL 替换
const ordinary = await webview.WebCookieManager.fetchCookie(url, false, false);
const withPartitioned = await webview.WebCookieManager.fetchCookie(url, false, true);

// 只记录布尔结果；不要把 Cookie 原文输出到控制台或埋点。
console.info(`hasAnyOrdinary=${ordinary.length > 0}`);
console.info(`rangeChanged=${ordinary !== withPartitioned}`);

rangeChanged=true 只说明两个读取范围的结果不同，不是“目标登录 Cookie 已经找回”的证据。应用不能靠 split(';') 随意把 Cookie 文本解析成可信身份；身份状态仍应由业务服务端验证。

案例二：无痕 Web 里已登录，应用却查普通存储

另一个常见误判与分区无关：页面按无痕模式打开，读取代码却固定传 incognito=false。此时第三个参数传 true 也不会自动切到无痕空间。应当先让读取模式与实际 Web 页面模式一致，再比较是否包含分区项。

import { webview } from '@kit.ArkWeb';

const url = 'https://example.com/account';
const normalMode = await webview.WebCookieManager.fetchCookie(url, false, true);
const incognitoMode = await webview.WebCookieManager.fetchCookie(url, true, true);
console.info(`normalHasAny=${normalMode.length > 0}`);
console.info(`incognitoHasAny=${incognitoMode.length > 0}`);

这里的对照并不意味着无痕里必定有 Cookie，或两个模式必定不同。只有测试页确实在对应模式写入了可读 Cookie，对照才有解释力。业务上最好由创建 Web 页面的一处代码同时保存其模式，并传给读取层；不要在读取层猜当前页面是否无痕。

把选择逻辑收口，避免两处参数传反

下面是可在 Node.js 运行的参数路由测试。它只证明我们的调用层会把 incognito 和 includePartitionedCookies 原样送到 API，不能代替 API 26 SDK 编译、Web 页面或真机 Cookie 测试。保存为 cookie-route.mjs，执行 node cookie-route.mjs。

import assert from 'node:assert/strict';

async function readForPage(api, page, includePartitioned) {
  if (!page.url.startsWith('https://')) throw new Error('Use a full HTTPS test URL');
  return api.fetchCookie(page.url, page.incognito, includePartitioned);
}

const calls = [];
const fakeApi = {
  async fetchCookie(url, incognito, includePartitioned) {
    calls.push({ url, incognito, includePartitioned });
    return 'test_only=1';
  }
};
const normal = { url: 'https://example.com/account', incognito: false };
const privatePage = { url: 'https://example.com/account', incognito: true };
assert.equal(await readForPage(fakeApi, normal, false), 'test_only=1');
assert.equal(await readForPage(fakeApi, normal, true), 'test_only=1');
assert.equal(await readForPage(fakeApi, privatePage, true), 'test_only=1');
assert.deepEqual(calls.map(x => [x.incognito, x.includePartitioned]),
  [[false, false], [false, true], [true, true]]);
await assert.rejects(readForPage(fakeApi, { url: 'http://example.com', incognito: false }, false));
console.log('4 route checks passed');

实际接入时把 fakeApi 换成 webview.WebCookieManager，但不要照搬演示中的测试 Cookie 字符串到生产日志。我的本地环境目前没有完成 API 26 编译与真机验证，因此这里不把“Node 测试通过”写成“HarmonyOS 7 实测通过”。真机复核应准备受控测试站点，分别在普通和无痕 Web 设置非敏感测试项，然后按上面三种参数组合读取，并核对页面模式、URL、服务端 Set-Cookie 条件。

什么时候不用改第三个参数

如果站点只使用普通非分区 Cookie，includePartitionedCookies 不会解决域名、路径、SameSite 或失效时间配置问题。华为的Cookie 管理指南在 2026-08-29 更新，说明未指定 SameSite 时默认 Lax；还说明 Cookie 周期性落盘和 saveCookieAsync 强制落盘的边界。读取不到与“重启后丢失”是两类问题，后者不要靠反复切换 fetchCookie 参数来修。

我的排查顺序是：先确认 API 26 重载能在项目 SDK 中编译；再核对完整 URL 与页面浏览模式；之后才对比是否包含第一方分区 Cookie；最后回到服务端下发条件和持久化边界。这样能把“查错存储空间”和“查对空间但读窄了范围”分开处理。