预加载JSON文件的Fetch请求未命中link preload问题排查

核心原因分析 #

浏览器复用预加载资源的前提是预加载配置与后续Fetch请求的所有关键参数完全匹配，哪怕是同源场景下的细微差异也会导致匹配失败，常见问题点包括：

• 请求模式（mode）与跨域凭证配置不匹配
• URL路径/参数存在大小写、绝对/相对路径差异
• 缓存策略（如协商缓存的Vary头）导致资源标识不统一
• Fetch请求执行时机超出预加载的有效时间窗口

针对性解决方案 #

1. 严格匹配同源请求的跨域配置 #

对于同源请求（本地localhost:4005和生产HTTPS同源场景），无需使用mode: 'cors'，应改用mode: 'same-origin'，同时对应预加载的crossorigin属性：

场景1：需要携带凭证（Cookie/HTTP认证）

预加载标签：

<link
  rel="preload"
  href="/_data/file.json"
  as="fetch"
  crossorigin="use-credentials"
>

Fetch代码：

fetch('/_data/file.json', {
  method: 'GET',
  mode: 'same-origin',
  credentials: 'include'
})

场景2：无需携带凭证

预加载标签：

<link
  rel="preload"
  href="/_data/file.json"
  as="fetch"
  crossorigin="anonymous"
>

Fetch代码：

fetch('/_data/file.json', {
  method: 'GET',
  mode: 'same-origin',
  credentials: 'same-origin'
})

2. 确保URL完全一致 #

• 检查dataPath是否与预加载的href完全匹配，包括路径大小写、是否带查询参数、绝对/相对路径转换后的一致性（比如避免./_data/file.json和/_data/file.json的差异）
• 本地环境出现Origin头而生产环境没有的情况，需确保服务器响应头的Vary字段不包含Origin，否则会导致预加载与Fetch请求的缓存键不统一

3. 控制Fetch请求执行时机 #

浏览器会在页面load事件后的几秒内回收未被使用的预加载资源，确保Fetch请求不要延迟过久执行（比如避免放在异步加载的脚本末尾或用户触发的事件中，除非确实需要延迟预加载）

4. 验证资源复用状态 #

打开浏览器DevTools的Network面板：

• 查看预加载请求的Status列，若显示(preload)且后续Fetch请求的Size列显示disk cache或memory cache，说明复用成功
• 若预加载请求的Initiator为Preload，但后续Fetch请求重新发起网络请求，说明参数匹配仍有问题

常见错误排查 #

• 若出现credentials mode does not match警告：直接对应上述跨域配置组合，确保crossorigin属性与credentials选项严格对应
• 若出现preloaded but not used报错：除了参数匹配问题，检查是否有脚本错误导致Fetch请求未执行，或请求被取消

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