React Query 垃圾回收

date

Nov 5, 2025

slug

react-query-waste-recycling

status

Published

🗑️ 为啥需要"扔垃圾"？

想象一下，你的冰箱（缓存）里塞满了各种剩菜剩饭。如果你从来不清理，会发生什么？

冰箱会爆满：内存是有限的，就像你家冰箱容量有限一样 💥

东西会变质：有些数据放太久，连当"过期食品"的资格都没了

找东西变困难：翻遍整个冰箱才能找到想要的东西

React Query 也面临同样的问题。它的缓存存在内存里，如果不定期清理，最终会导致：低端设备内存爆炸、存一堆没用的"古董数据"、应用越来越卡。

所以，React Query 内置了自动垃圾回收机制！

⏰ `gcTime`：你的"保质期标签"

React Query 使用 gcTime（Garbage Collection Time，垃圾回收时间）来决定何时扔掉缓存数据。

⭐ 默认值
默认值是 5 分钟（1000 * 60 * 5）。

但注意！这不是说"5分钟后就扔"，而是说：

"没有人使用（非活跃）之后，再等 gcTime 时长才彻底删除。"

这就像办公室的咖啡：

有人在喝 = 数据被活跃使用 = 不能扔

没人喝了 = 开始计时，gcTime 之后扔掉

什么叫"活跃使用"？

每次调用 useQuery，都会创建一个 Observer（观察者）。

有 Observer 盯着 = 活跃 = 不会进入回收倒计时

没有 Observer = 非活跃 = 开始倒计时（gcTime）

🧠 `gcTime` vs `staleTime`

这是最容易混淆的两个时间设置：

时间属性	作用	默认值
`staleTime`	数据多久后算“过期”（但仍可使用）	0 毫秒
`gcTime`	数据多久后算“垃圾”（彻底从内存中删除）	5 分钟

关系总结： gcTime 必须大于或等于 staleTime。因为数据都删了，也就不存在“新鲜”还是“过期”的说法了。

🎬 实战案例：搜索功能的缓存管理

让我们用搜索功能来演示 gcTime 的效果：

场景模拟：

搜索 "React" → 缓存：['issues', 'React'] 活跃

切换到 "Vue" →

新缓存：['issues', 'Vue'] 活跃

旧缓存：['issues', 'React'] 变非活跃，开始 3 秒倒计时 ⏰

3 秒内再搜 "React" → 缓存重新变活跃，**爽！**😎

3 秒后搜 "React" → 缓存已被清理，重新加载... 😅

🎨 自定义垃圾回收策略

不同场景需要不同的清理策略：

场景	gcTime	staleTime	策略说明
用户信息	30 分钟	10 分钟	变化慢，保留久一点，减少不必要的请求。
实时股价	1 分钟	0 毫秒	变化快，看完就扔，数据永远是“过期”状态，易触发更新。
静态配置	`Infinity`	24 小时	数据几乎不变，永不清理。

📋 关键要点总结

gcTime vs staleTime：staleTime 管可用性，gcTime 管内存占用。

“活跃”的定义：有 Observer（组件正在使用）即为活跃，不会被回收。

回收时机：当 Observer 数量为 0 时，gcTime 开始倒计时。

合理设置：根据数据变化频率和内存需求合理配置 gcTime，并且永远不要设置 gcTime < staleTime。

记住：React Query 的垃圾回收就像个贴心的清洁工，默默地帮你保持缓存整洁。合理的垃圾回收策略 = 更好的性能 + 更少的内存占用 + 更爽的用户体验！

下一步我想做的：

我们已经覆盖了查询的方方面面。接下来您希望我：

讲解手动更新：聊聊如何跳过网络请求，直接通过 queryClient 手动修改缓存数据（比如用户在前端提交表单后，直接更新列表）。

讲解 useMutation：聊聊如何处理写操作（POST/PUT/DELETE），并结合缓存失效实现数据乐观更新（Optimistic Updates）。