Storage Access API 用于解决跨源 iframe 中 Cookie 和存储访问被浏览器默认隔离的问题，需在用户手势触发下调用 requestStorageAccess() 申请权限，仅恢复当前 iframe 对第一方存储的访问能力，不改变同源策略或替代 Web Storage。
Storage Access API 不是用来“存数据”的，它解决的是第三方上下文（比如 iframe）里被浏览器默认阻止的 Cookie 和存储访问问题。如果你在 iframe 里调用 localStorage.setItem() 或读取 document.cookie 报错、静默失败，或者登录态无法透传，那才需要它。
直接结论：你不需要主动“做” Storage Access API，除非你的网站嵌入了跨源 iframe，且该 iframe 需要访问第一方存储（如登录态、偏好设置）。
为什么 iframe 里 localStorage / cookie 突然失效了？
现代浏览器（Safari、Firefox、Chrome 84+ 默认开启）对第三方上下文施加了存储分区（storage partitioning）策略：iframe 加载非同源页面时，其 document.cookie、localStorage、indexedDB 等默认被隔离或清空——即使用户已登录主站，iframe 也拿不到凭证。
常见现象包括：
立即学习“前端免费学习笔记（深入）”；
- 嵌入的广告/分析 iframe 无法写入
document.cookie，报SecurityError: The operation is insecure - 嵌入的 SSO 登录组件在 iframe 中调用
requestStorageAccess()失败，返回Promised rejected - 用户点击登录按钮后，iframe 内仍显示“未登录”，
hasStorageAccess()返回false
Document.hasStorageAccess() 怎么用？
这是检测当前文档是否已有存储访问权限的唯一可靠方式。它不触发弹窗，也不请求权限，只返回一个 Promise。
典型用法：
document.hasStorageAccess().then(hasAccess => {
if (hasAccess) {
// 可安全使用 localStorage / cookie
} else {
// 需要 requestStorageAccess()
}
});
注意点：
- 必须在用户手势（如
click、tap）触发的事件处理函数中调用，否则 Chrome 会拒绝 Promise - Safari 要求页面必须启用
document.featurePolicy.allowedFeatures().includes('storage-access-api')（实际极少需手动配） - 返回
true仅表示“当前已授权”，不代表未来一直有效（如用户清除了站点数据）
requestStorageAccess() 必须由用户点击触发
这是唯一能申请存储访问权限的方法，且有严格限制：
- 只能在
user activation上下文中调用，即紧接在click、keydown（仅限可聚焦元素）、submit等事件回调内 - 不能在
setTimeout、fetch.then、load事件里调用，否则 Promise 永远 pending 或 reject - 调用后浏览器会弹出轻量级权限提示（Safari 最明显），用户点“允许”才真正生效
- 成功后，
document.cookie和localStorage将恢复为第一方上下文行为，但sessionStorage仍按 iframe 会话隔离（它本就不跨 tab 共享）
错误示例：
// ❌ 错误：异步回调中调用
button.addEventListener('click', () => {
fetch('/check').then(() => document.requestStorageAccess()); // 拒绝
});
<p>// ✅ 正确：立即调用
button.addEventListener('click', () => {
document.requestStorageAccess()
.then(() => console.log('granted'))
.catch(err => console.warn('denied or blocked', err));
});
Storage Access API 不解决什么问题
它不是 Web Storage 的替代品，也不修复以下场景：
- 同源页面直接使用
localStorage或sessionStorage—— 完全不需要它 - 想绕过同源策略读取其他域名的
localStorage—— 不可能，API 本身受同源限制 - iframe 内需要持久化大量结构化数据 —— 应优先用
IndexedDB（它在存储分区下仍可创建独立库），而非依赖requestStorageAccess() - 服务端 Cookie 被
SameSite=Lax/Strict阻止 —— 这是 Cookie 属性问题，和 Storage Access API 无关
最容易被忽略的一点：Storage Access API 的权限是**逐 origin + 逐 iframe 实例**授予的。同一个嵌入方在不同页面、或同一页面多个 iframe 实例，都要各自申请；而且 Safari 会在用户关闭标签页后自动撤销权限，下次打开还得再点一次。
