@tanstack/preact-query 安装指南：为 Preact 项目引入 TanStack Query 的完整实操方案
本文围绕 TanStack Query 的 Preact 框架适配包 @tanstack/preact-query 展开，系统讲解在 Preact 项目中安装、引入该数据请求与状态管理库的全部可行路径（包管理器安装、ESM CDN 引入），并结合当前仓库的包元数据与官方示例，给出版本约束、验证方式与后续上手入口，帮助你在正式开始书写 useQuery 之前，先把依赖装对、跑通、可复现。
先说清：你要安装的东西是什么
在开始执行命令前，先确认安装对象的本质。本仓库是一个 pnpm 管理的 TypeScript monorepo（见 pnpm-workspace.yaml），TanStack Query 的 Preact 适配层位于 packages/preact-query，其包描述为 "Hooks for managing, caching and syncing asynchronous and remote data in preact"。
从 packages/preact-query/package.json 可以看出三个关键事实：
- 包名：
@tanstack/preact-query，当前仓库内版本为5.102.8； - 运行时依赖：
@tanstack/query-core（workspace 内即 packages/query-core），也就是说缓存、重试、失效等核心引擎都在 query-core，preact-query 只负责把核心引擎适配为 Preact 可用的 hooks； - peerDependencies：
preact: ^10.0.0——这意味着你的项目必须已有 Preact v10，preact-query 不会替你安装 Preact。
同时，包采用双格式产物（module/main 分别指向 build/modern/index.js 与 build/legacy/index.cjs），并声明 sideEffects: false，具备良好的 tree-shaking 条件。
安装前的前置条件
在把 @tanstack/preact-query 加入项目之前，请先确认环境满足以下前提：
- Preact v10 及以上：这是 preact-query 的 peer 依赖硬性约束（
preact: ^10.0.0）； - 支持原生 ESM 的现代运行环境：preact-query 面向现代浏览器与基于 ESM 打包器的工程；
- 选择了安装通道：有模块打包器 / 包管理器的工程走 NPM 通道；无打包器的简单页面可走 CDN 通道（见下文）。官方文档的原话是：如果你想在下载前先试运行，可以直接跑仓库里的 simple 示例。
方式一：使用包管理器安装（工程化项目推荐）
Preact 版安装文档由 docs/framework/react/installation.md 经由 react-query → preact-query、React → Preact 替换生成（可见于 docs/framework/preact/installation.md 的 frontmatter），因此 React 版安装文档中的各包管理器命令对 Preact 版同样成立，仅包名替换为 @tanstack/preact-query。
在本仓库中，官方 simple 示例 正是通过以下依赖声明安装的：
{
"dependencies": {
"@tanstack/preact-query": "^5.102.8",
"preact": "^10.28.0"
}
}
你可以按项目实际使用的包管理器任选其一：
npm
npm i @tanstack/preact-query
pnpm（本仓库 monorepo 默认使用 pnpm）
pnpm add @tanstack/preact-query
yarn
yarn add @tanstack/preact-query
bun
bun add @tanstack/preact-query
deno
deno add @tanstack/preact-query
安装完成后，可在 package.json 中确认依赖已写入，且版本位于 v5.x 线（与仓库内 5.102.8 保持一致或更高）。需要注意：命令会同时解析并校验 peer 依赖 preact@^10，若项目 Preact 版本过低，包管理器会给出 peer dependency 冲突提示，此时应先升级 Preact。
方式二：通过 ESM CDN（esm.sh）零打包引入
如果你的场景不涉及模块打包器或包管理器——例如一个简单的 HTML 页面、快速原型、CodePen 式的在线演示——可以直接用 ESM 兼容 CDN esm.sh 引入。这是官方安装文档中唯一保留的完整代码示例，在 HTML 文件的 <body> 底部添加 <script type="module"> 即可：
<script type="module">
import { render } from 'https://esm.sh/preact@10.23.1'
import { QueryClient } from 'https://esm.sh/@tanstack/preact-query'
</script>
关于这段示例有两点值得注意：
- Preact 版本被显式钉在
10.23.1：CDN 引入时建议始终钉住具体版本（通过@版本号语法），避免后续 CDN 上浮动的 major 升级破坏 peer 兼容性； QueryClient从@tanstack/preact-query导出：结合 packages/preact-query/src 源码结构可知，框架包同时导出了QueryClientProvider、useQuery、useMutation等 hooks 与 Provider。这意味着通过 CDN 也能完成"创建 QueryClient → 挂载 Provider → 组件内调用 hooks"的完整链路，只是需要按需补齐对应导出。
沿用 CDN 通道时，可在同一 <script type="module"> 中继续 import 你需要的其余 API（如 QueryClientProvider），无需经过任何打包步骤；浏览器会负责解析 ESM import map 层级。
安装后如何快速验证：跑通官方 simple 示例
依赖装完不等于万事大吉，最稳妥的验证方式是直接运行仓库中的官方示例。文档特别推荐在下载使用前先试跑 simple 示例，它的工程配置位于 examples/preact/simple/package.json：
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"dependencies": {
"@tanstack/preact-query": "^5.102.8",
"preact": "^10.28.0"
},
"devDependencies": {
"@preact/preset-vite": "^2.10.2",
"vite": "^6.4.1"
}
}
其验证步骤为：
pnpm install—— 安装全部依赖（在 monorepo 根目录执行会同时安装工作区内所有包）；pnpm dev—— 启动开发服务器（默认 http://localhost:5173/），页面能正常渲染并发出请求即代表安装与集成成功；pnpm build&&pnpm preview—— 构建产物到dist/后在 http://localhost:4173/ 预检生产构建。
该示例的源码入口在 examples/preact/simple/src/index.tsx，配合 vite.config.ts 使用 @preact/preset-vite 完成 JSX/TSX 编译。若你打算把示例复制到自己的新工程，可照搬这组 devDependencies，它是 Preact + Vite 工程的标准底座。
安装成功后，下一步怎么走
依赖就位后，官方推荐按以下路径继续深入（各指南均位于 docs/framework/preact 框架文档目录下）：
- 核心查询用法：先阅读 queries 指南，掌握
useQuery的 queryKey / queryFn / 返回对象语义； - 默认行为与坑点：阅读 important-defaults 指南，理解 staleTime、gcTime 等默认值，避免"刚装好就觉得库不刷新"的误解；
- 变更类操作：涉及写操作时参考 mutations 指南 与 optimistic-updates 指南；
- 调试工具：可选安装官方调试面板（对应参考文档 devtools.md）；
- 持久化：若需要把缓存写入 localStorage 等存储介质，preact-query 生态在仓库中另有 packages/preact-query-persist-client，与 query 主体分开安装；
- 静态检查：仓库同时维护框架无关的官方 ESLint 插件 packages/eslint-plugin-query（文档位于 docs/eslint），可作为可选的开发期质量增强，按需以
-D安装。
浏览器与兼容性基线
安装决策还应包含运行环境评估。需要说明的是：当前 docs/framework/preact/installation.md 是 React 版安装文档经关键词替换生成的派生页面，浏览器兼容基线的权威表述保留在作为模板的 React 版 docs/framework/react/installation.md 中，其声明该系列 Query 库面向现代浏览器优化，兼容基线大致为 Chrome >= 91、Firefox >= 90、Edge >= 91、Safari >= 15、iOS >= 15、Opera >= 77。若需支持更老的浏览器，通常需要自行添加 polyfill，并对 node_modules 中的库代码进行转译。这一点对 preact-query 具有同等参考意义。
小结
无论是走包管理器还是 ESM CDN，@tanstack/preact-query 的安装都有清晰、可验证的路径：前置条件是 Preact v10+；工程化项目用 npm/pnpm/yarn/bun/deno add @tanstack/preact-query；轻量页面用 esm.sh 以 <script type="module"> 引入并钉住版本；装完用仓库 simple 示例 一键 pnpm dev 验证。依赖就位之后，即可进入 TanStack Query 的核心使用环节——从 queries 指南 开始书写你的第一个 useQuery。
相关内容推荐
atomcodeClaude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get StartedRust0629
MiniCPM5-2BMiniCPM5-2B 是一款面向端侧、本地部署和资源受限场景的 2B 稠密 Transformer，能够达到同尺寸开源模型 SOTA 水平。Markdown00
GLM-5.3GLM-5.3 与 GLM-5.2 使用相同的基座模型——所有提升均来自后训练。与 GLM-5.2 相比，它在复杂编程和长程任务上的表现显著提升。Jinja00
HivisionIDPhotos⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。Python07
DragonOSDragonOS is an operating system developed from scratch using Rust, with Linux compatibility. It is designed for **Serverless** scenarios. 使用Rust从0自研内核，具有Linux兼容性的操作系统，面向云计算Serverless场景而设计。Rust00
Spark-X2.5-1.7BSpark-X2.5-1.7B 旨在让强大的 AI 更加实用、高效且易于获取。这些模型在广泛的日常任务中表现出色，涵盖对话、写作、翻译、推理、编程、工具调用和智能体工作流，并在同等规模的开源模型中取得领先结果。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合，并支持 200 多种语言。Python00
热门内容推荐
最新内容推荐
项目优选
kernel
ops-transformer
pytorch
docs
kernelops-nn
jiuwenswarmops-mathcann-learning-hubAscendNPU-IR