Apollo Client乐观更新新增列表项分离详情查询致缓存未命中

API 探路者

2026-8-27

问题成因

核心是Apollo Client分层缓存的隔离机制未被正确触发：Apollo的缓存分为永久缓存层、独立的乐观事务缓存层，乐观mutation通过optimisticResponse生成的临时实体（带临时乐观id）只会存放在乐观层，mutation完成前不会写入永久层。如果在update回调中写入列表数据时，没有正确建立列表条目和乐观层实体的引用关系，两层数据不会自动关联。
缓存引用断裂是最常见的触发场景：手动写入列表query缓存时，如果只插入了裸id值，没有携带对应实体的__typename字段，Apollo的归一化逻辑无法将这个id和乐观层中存储的同id实体关联，会判定该条目对应实体不存在，子组件触发详情query时自然读不到缓存。
查询字段不匹配也会导致缓存命中失败：如果optimisticResponse里只返回了实体id，没有覆盖子组件详情query要求的所有字段，就算引用关系正确，Apollo也会判定当前缓存数据不满足查询需求，触发兜底逻辑。
部分场景下是fetchPolicy配置错误：如果子组件的详情query设置了network-only/no-cache这类不优先读缓存的策略，会直接跳过乐观缓存发起请求，临时乐观id对应的接口请求必然返回空，就会渲染not found兜底。

修复方案

按以下步骤调整即可解决：

补全optimisticResponse的字段，保证和子组件详情query请求的字段完全对齐，不要只返回id：

const [addItem] = useMutation(ADD_ITEM, {
  optimisticResponse: {
    addItem: {
      __typename: 'Item', // 必须和schema定义的类型名完全一致
      id: `temp-${Date.now()}`, // 临时乐观id
      // 下面的字段和详情query要求的字段一一对应
      title: '新建条目（保存中）',
      desc: '内容正在提交，请稍候',
      createdAt: new Date().toISOString()
    }
  },
  // 其余配置
})

在update回调中写入列表缓存时，给新条目携带正确的__typename，保证缓存引用可被归一化识别：
```
update(cache, { data }) {
  const { itemList = [] } = cache.readQuery({ query: ITEM_LIST_QUERY }) || {}
  cache.writeQuery({
    query: ITEM_LIST_QUERY,
    data: {
      // 新条目必须带__typename，不要只写{id: xxx}
      itemList: [...itemList, { __typename: 'Item', id: data.addItem.id }]
    }
  })
}
```
不需要额外判断isOptimistic，只要传入了optimisticResponse，Apollo会自动在乐观事务阶段将这次write写入乐观层，mutation完成后会用真实返回值重跑update写入永久层，不会出现跨层污染。
检查子组件详情query的配置：
- 确认fetchPolicy使用默认的cache-first，不要配置为跳过缓存的策略
- 确认query请求的字段和optimisticResponse、mutation真实返回的字段完全对齐，不要请求乐观数据里不存在的字段
- 不要给详情query加额外的条件跳过渲染（比如判断id是临时id就不发query，这会导致直接读不到缓存）
可选优化：写入列表时直接使用cache.identify生成标准缓存引用，彻底避免__typename写错的问题：
```
update(cache, { data }) {
  const newItemRef = cache.identify(data.addItem)
  cache.modify({
    fields: {
      itemList(existingRefs = []) {
        return [...existingRefs, { __ref: newItemRef }]
      }
    }
  })
}
```
用cache.modify直接操作缓存字段的引用，比writeQuery更可靠，不会因为query字段变更导致写入失效。

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

Apollo Client乐观更新新增列表项 分离详情查询致缓存未命中

Apollo Client乐观更新新增列表项分离详情查询致缓存未命中