为何网站访客会遇到kCFErrorDomainCFNetwork error 310报错

错误定义 #

该错误是苹果生态（iOS、macOS下所有基于WebKit内核的浏览器，包括Safari、Chrome for iOS、Edge for iOS等）专属的网络层错误，错误码310的核心指向是跨源上下文下的网络请求被浏览器安全策略拦截，绝大多数触发场景都和iframe嵌入、跨源资源访问限制直接相关。

你场景下20%~30%报错率的核心诱因 #

• Safari智能跟踪预防（ITP）策略限制：Safari默认会拦截第三方iframe在未获得用户主动交互前的所有cookie、localStorage等存储访问权限，如果你嵌入的Next.js页面初始化阶段就需要读取存储、或发起携带凭证的跨源请求，未授权的情况下请求会被直接拦截抛出该错误。目前Safari全球浏览器市场份额约为20%，加上其他基于WebKit的移动端浏览器占比，和你观测到的报错率区间完全吻合，这是最主要的触发原因。
• Netlify默认安全头配置冲突：Netlify默认会给站点资源添加X-Frame-Options: SAMEORIGIN、Content-Security-Policy: frame-ancestors 'self'安全头，如果你没有将合法嵌入方的域名显式加入白名单，部分WebKit内核浏览器不会直接展示跨源嵌入禁止提示，反而会抛出该网络层错误。
• HSTS配置异常：如果你站点的HSTS规则包含includeSubDomains或preload属性，但嵌入方页面是HTTP协议，或者你站点的子域名存在证书不匹配问题，WebKit内核的网络层会直接终止连接，抛出310错误。

快速排查与修复方案 #

• 先在Safari的「设置」-「隐私与安全性」中关闭「阻止跨站跟踪」选项，复现嵌入场景，如果不再报错即可确认是ITP策略导致的问题。
• 调整Netlify的响应头配置，在netlify.toml中添加所有合法嵌入方域名到CSP白名单：

[[headers]]
  for = "/*"
  [headers.values]
    Content-Security-Policy = "frame-ancestors 'self' https://你的嵌入方域名1 https://你的嵌入方域名2;"

• 如果嵌入页面需要使用存储或携带凭证的请求，先引导用户在iframe中完成一次主动交互（比如点击确认按钮），之后Safari会给该嵌入站点授予7天的临时存储访问权限，即可避免拦截。

内容的提问来源于stack exchange，提问作者Jo Sprague