TanStack DB 1.0 RC1:新特性与升级指南(2026)

TanStack DB 1.0 RC1 正式发布:新增服务端渲染与 TanStack Start 集成、Neon Realtime 与 Convex 适配器,并将 $synced 迁移为语义反转的 $hasPendingWrites。本文面向 SaaS 团队解读新特性、oracle 测试加固与完整升级清单。

Huifer
Huifer
October 30, 20269 min read
其他语言:Deutsch · English

本文由 Huifer 撰写,他是 TanStack Ship 的独立开发者与维护者。自 2024 年起,我一直在生产环境中交付并维护 TanStack Ship 模板,而本指南——《TanStack DB 1.0 RC1:新特性与升级指南(2026)》——反映的正是我实际运行的配置。以下全部内容都是我日常所用的东西,包括我踩过的故障模式以及如何解决它们。

已验证来源:TanStack Start 文档 · TanStack Query 文档 · Cloudflare Workers 文档 · Stripe 文档

最后更新:2026-10-30 · 更新日志

本文由 Huifer 撰写 | 最后更新:2026-10-30 | 更新日志

我从 2025 年初开始在 TanStack Start 上交付 SaaS 应用,而每一个项目都会撞上同一堵墙:用户编辑数据时,仪表盘不停地请求、重新请求、闪烁。我维护着 TanStack Start 样板工程 TanStack Ship,所以这种规模的客户端数据层变革直接决定下一代模板该带什么。RC1 在 2026-10-29 发布当天上午,我读完了发布公告和完整的迁移指南,并逐条对照了我们的技术栈。我还没有把生产应用迁到 RC,我也会明确说出我会在哪些地方继续观望。

验证来源:TanStack DB 1.0 RC1 发布公告 与官方迁移指南。

TL;DR

  • RC1 于 2026-10-29 发布,此前经过 18 个月开发,见官方公告
  • 核心包 @tanstack/db 的每周 npm 下载量突破 100 万,较过去一年增长约 10 倍(实测自 npm)
  • 自 0.6 以来的变化:服务端渲染、TanStack Start 集成、Neon Realtime 与 Convex 适配器,以及作为第六个框架适配器的 Preact
  • 1.0 加固工作新增约 42 万行测试,分布在 15 个包中的 211 个 oracle 测试文件里
  • 最大的破坏性变更:移除 $synced,由布尔语义相反的 $hasPendingWrites 取代
  • 我的评分:对既有 TanStack Query 应用的渐进式采用给 9/10,第一天就把生产环境押在 RC 上给 6/10

TanStack DB 1.0 RC1:新特性与升级指南(2026)

TanStack DB 是一个响应式客户端数据框架,让后端数据用起来像本地数据:API 或同步引擎的记录变成带类型的集合,组件对集合运行带联表和过滤的实时查询,乐观修改即时呈现、稍后再与后端对账。RC1 是十八个月公开 beta 之后的 API 稳定性里程碑。

概念模型我在《TanStack DB 深度解析》中讲过。本文是发布分析:自 0.6 以来交付了什么、这次发布如何完成加固,以及迁移清单。

RC1 自 0.6 以来的交付:四项具体新增

服务端渲染与 TanStack Start 集成

beta 与"框架级数据层"之间最大的缺口是 SSR,现在这个缺口关闭了:DB 带着与 TanStack Start 的深度集成交付服务端渲染。对 SaaS 仪表盘来说,这比任何查询 API 的细节都重要——纯客户端数据层会让首屏出现加载转圈,这正是 DB 要消灭的闪烁问题。这里先标记迁移指南里的一个细节:SSR 数据必须显式准备,注水得到的行会被当作临时种子数据,而不是已确认的服务端状态。写集合代码之前,先读 SSR 迁移章节。

Neon Realtime 与 Convex 的集合适配器

适配器是 DB 连接后端的方式,而且不需要改动你的查询代码。自 0.6 以来,项目新增了 Neon Realtime 支持和一个 Convex 适配器。Neon 的加入并非偶然:DB 在头十八个月里由 ElectricSQL 孵化,Neon 在八月收购了 ElectricSQL,随后推出了一等支持 TanStack DB 的 Neon Realtime。想要实时同步的 Postgres 开发者,现在有了一条从数据库出发、有供应商背书的路径。

Preact:第六个框架适配器

Preact 适配器把框架支持数量带到六个:React、Vue、Solid、Svelte、Angular,以及现在的 Preact。每个框架包都重新导出核心 @tanstack/db 引擎,因此集合和实时查询 API 在各框架之间保持一致——对于想在多个应用上统一使用同一个响应式客户端数据层的团队来说,这一点很有用。

rc dist-tag 与"RC"在实践中的含义

第一个候选版本是 1.0.0-rc.1,发布在 npm 的 rc dist-tag 下而不是 latest——一个带逃生通道的稳定 API。迁移指南里有个小插曲:@tanstack/query-db-collection 和 @tanstack/offline-transactions 在 RC 之前被误发成了 1.0;请让这两个包停留在它们最新的 1.x 版本上,它们以 @tanstack/db@^1.0.0-rc.0 作为 peer 依赖。

渐进式采用路径:先接 REST API,再上离线

正是这一点把 DB 与更早的客户端数据库区分开来。过去,响应式查询、乐观变更和离线支持意味着一步到位地采用一套新数据库和同步架构。DB 把这个顺序倒了过来:从你现有的 REST API 和 TanStack Query 配置出发,立刻获得渐进式的联表实时查询,然后只在需要时再加 SQLite 持久化、持久化离线事务或实时同步。

由于面向应用的查询模型在每一步都保持不变,从常规 Web 应用走向完全离线可用的 local-first 应用,并不需要重写你的数据层。各个层级对应你的风险预算:

层级你新增什么你得到什么
1在 REST API 之上使用 Query Collection带类型的集合、实时查询、乐观修改
2SQLite 持久化刷新页面后本地数据仍保留
3持久化离线变更写入能在重启与重连后保留
4Neon Realtime 或 ElectricSQL实时多客户端同步

对 SaaS 仪表盘来说,落到实践就是:管理后台的列表视图在编辑时变得即时,表单不再闪烁,而且后端端点一行都不用改。这就是"后端数据用起来像本地数据"的卖点,从官方指南看,我认为在第 1 层级、不需要奇特基础设施的情况下它就成立。

DB 如何完成加固:211 个 oracle 与 42 万行测试

1.0 的故事一半在功能,一半在过程。Kyle Mathews 写道,服务端渲染落地之后,他原以为只是一次短暂的修 bug 远征。结果变成了数百个 PR 和数月的工作,仓库新增了约 42 万行测试——由编码代理(coding agent)对照测试 oracle 而非基于示例的单元测试驱动完成。

从示例测试到基于模型的 oracle

测试 oracle 是一个独立计算的模型,用来算出正确答案,而不是人工记录一份期望输出。DB 的 oracle 把 fast-check 的基于属性的生成与纯 JavaScript 参考模型配对:模型从零重新计算每一个实时查询结果,而 DB 以增量方式维护它,每批变更之后两者必须一致。DB 现在有分布在 15 个包中的 211 个 oracle 测试文件,并附有一张覆盖地图,让编码代理在改代码之前先找到相关的不变式。

这些方法抓到的 bug 不是假设。Issue 1901:在同一个事件循环轮次里删除再重新插入相同 key 的行,会让订阅者拿到过期缓存,已在 PR 1902 修复。执行消息不变式——insert 要求 key 不存在、update 和 delete 要求 key 存在——导致 378 个既有用例中的 26 个失败,并暴露出一个已在 PR 1995 修复的生产 bug。对最难的规则,团队会先用 TLA+ 做原型,再把模型翻译成可执行的 TypeScript oracle。

**之前:**基于示例的测试只保存了孤立的答案;bug 只能靠用户复现才会浮出水面。 **之后:**oracle 强制执行的设计不变式能在发布前暴露整类失败;只要承诺仍然成立,编码代理就可以重写内部实现。 **验证:**撰写本节时,我把上述每个修复都追溯到了对应的公开 PR。

升级:1.0 RC 迁移清单

官方迁移指南覆盖了从 @tanstack/db@0.9.2 到 1.0.0-rc.1 的路径。以下变更会触及真实的应用代码:

一起更新所有包,从 rc tag 安装

bash
npm install @tanstack/react-db@rc @tanstack/electric-db-collection@rc

在同一个提交里更新所有 1.0 之前的 DB 包——适配器以 RC 为 peer 依赖,混用版本正是指南第一个警告的失败模式。

用 $hasPendingWrites 替换 $synced

被移除的 $synced 虚拟属性有一个语义相反的替代品。这是最可能从"改个名然后祈祷"式迁移中溜过去的一个变更:

变更前变更后
row.$synced!row.$hasPendingWrites
!row.$syncedrow.$hasPendingWrites
eq(row.$synced, true)eq(row.$hasPendingWrites, false)
eq(row.$synced, false)eq(row.$hasPendingWrites, true)

语义也变得更精确:$hasPendingWrites 表示是否有未完成的本地乐观变更影响该行,而仅凭 false 并不能证明服务端已确认这次写入。

变更处理器、事务与 SSR 种子数据

三个行为变更需要阅读代码,而不只是重命名符号。第一,等待事务落定——即发即忘(fire-and-forget)的写入需要显式 await。第二,变更处理器必须在内部等待同步完成,而且 Query Collection 的处理器不再在变更后重新请求,这去掉了很多应用一直依赖的隐藏往返。第三,显式准备 SSR 数据,并把注水得到的行当作临时种子。其余条目:显式导入 includes 和分组操作符、把嵌套选择包在 include() 里、使用字符串或数字 key,并通过新的 reload() 重试路径把加载失败与同步问题区分开。

采用现状核实:谁在生产环境运行 TanStack DB

RC 发布公告点名了三个生产用户:Prisma Studio、Unkey 的开发者仪表盘,以及依赖 DB 离线能力的 Skylight React Native 家庭日历。核心包每周下载量超过 100 万,约占 React 每周下载量的 0.6%,同比增幅约 10 倍——这是一条真实的采用曲线,不是发布日的一次性脉冲。如果你曾在 TanStack Query 里手写乐观更新——正如我在《TanStack Query 乐观更新》中记录的那样——DB 会把其中大部分管道工作自动化。

基于 TanStack Start 的 SaaS 现在就该采用 RC 吗?

**问题:**仪表盘上每一次编辑都触发重新请求、缓存失效和肉眼可见的闪烁。 **根因:**客户端状态库把服务端数据当作"待失效的缓存",而不是"可查询的数据集"。 **解决方案:**用集合承载实时查询和带事务性的乐观变更。 **结果:**编辑在同一帧内生效,对账无需手动管理缓存管道。

这就是诚实的收益面。我对 TanStack Ship 技术栈的采用建议:第 1 层级采用(在既有 REST 端点上使用 Query Collection)作为单个仪表盘页面、放在 feature 分支上的评估项目是合理的。在 1.0 正式版发布之前,我不会把持久化离线变更或实时同步放进生产模板——迁移指南记录了行为层面的微妙之处(消息顺序、落定时序、SSR 种子),这些需要等一个稳定版本来对照。RC 的稳定承诺针对的是 API 表面,不是让你跳过自己的集成测试的许可证。

局限与坦诚披露

我通过阅读发布公告、迁移指南和相关 PR 评估了这个 RC——我还没有把任何生产应用迁到 1.0.0-rc.1,因此无法报告第一手的升级耗时。性能声明来自维护者,本文未做基准测试。我与 Neon、ElectricSQL、Prisma、Unkey 或 Skylight 没有任何实质利益关联。发布事实均标注为来自上述官方来源的实测(Measured);采用判断是我个人的判断。

结论与下一步

TanStack DB 1.0 RC1 是十八个月 beta 变成稳定性契约的时刻:SSR 与 Start 集成补齐了渲染缺口,Neon Realtime 和 Convex 拓宽了后端覆盖面,六个框架获得支持,oracle 驱动的测试体系用约 42 万行新测试加固了核心。渐进式路径意味着你的 REST API 不是负担——它就是起点层级。

下一步:挑一个读多写少的仪表盘页面,在分支上接上一个 Query Collection,对比编辑闪烁的前后差异。当你想要这套东西所属的完整技术栈时,可以对比 TanStack Ship 与你当前框架的差异,或者阅读深度解析了解查询引擎的基础原理。

FAQ:TanStack DB 1.0 RC 与升级

TanStack DB 1.0 稳定吗?

还不是正式版——RC1(1.0.0-rc.1)于 2026-10-29 发布,维护者称 API 已达到生产可用且稳定。最终 1.0 会在 RC 阶段之后发布;在此之前请从 rc dist-tag 安装。

如何从 $synced 迁移到 $hasPendingWrites?

把布尔值反过来:row.$synced 变成 !row.$hasPendingWrites,!row.$synced 变成 row.$hasPendingWrites。包括查询层 eq() 改写在内的完整映射见迁移指南。

TanStack DB 会取代 TanStack Query 吗?

不会。它是对 Query 的扩展——Query Collection 构建在 TanStack Query 之上,迁移路径从你现有的 Query 配置出发,而不是替换它。

可以在纯 REST API 上使用 TanStack DB 吗?

可以,而且这正是设计好的起点。第 1 层级采用会让你的端点保持不变,集合和实时查询全部在客户端运行。