Solid Query 安装指南：NPM 安装、CDN 引入与浏览器兼容性要求-育师

Solid Query 安装指南：NPM 安装、CDN 引入与浏览器兼容性要求

【免费下载链接】query🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query

本文导读：Solid Query（@tanstack/solid-query）是 TanStack Query 生态中面向 Solid.js 的官方数据请求与异步状态管理方案。本文将基于安装文档完整梳理它的三种引入方式（NPM / pnpm / yarn / bun 包管理器安装、ESM CDN 引入），并逐条解读官方推荐的浏览器兼容范围与老浏览器场景下的转译建议；同时结合本仓库内的真实package.json、示例工程与源码结构，给出安装后快速验证与工程化落地的实操指引。读完你可以独立完成 Solid Query 的选型安装、环境校验与首个可运行示例。

一、安装前先认识包结构

在 packages/solid-query 目录内可以看到完整的 SDK 工程。其 package.json 中定义的关键信息如下：

包名：@tanstack/solid-query，当前仓库内版本为5.102.8；
定位：Primitives for managing, caching and syncing asynchronous and remote data in Solid，即为 Solid 提供管理、缓存与同步异步/远端数据的响应式原语；
运行时依赖：仅依赖@tanstack/query-core（同仓库 workspace 版本），核心查询引擎与 UI 层原语分层解耦；
Peer 依赖：solid-js: ^1.6.0，即安装方需要自行提供兼容的 Solid 运行时，官方在^1.6.0及以上版本范围内均可用；
产物形态：exports字段同时声明了import/require两套入口（ESM 与 CJS），并额外提供development条件导出，便于开发期与生产期加载不同的构建产物。

这些字段是包管理器在安装、解析与打包时依赖的真实依据。理解它们，有助于你在 Vite、Solid Start 或传统构建工具中遇到解析告警时快速定位问题。

二、通过包管理器安装（NPM）

官方推荐通过 NPM 生态安装。文档给出了四种主流包管理器完全等价的命令：

npm i @tanstack/solid-query

或：

pnpm add @tanstack/solid-query

或：

yarn add @tanstack/solid-query

或：

bun add @tanstack/solid-query

版本与配套说明

本仓库为 TanStack Query v5 系列，安装@tanstack/solid-query后，可直接导入QueryClient、QueryClientProvider、useQuery、useQueries、useInfiniteQuery、useMutation等 API（这些导出在 packages/solid-query/src 的useQuery.ts、useQueries.ts、useInfiniteQuery.ts、useMutation.ts、QueryClient.ts等文件中一一对应）。
若使用 pnpm 工作区（如本仓库采用 pnpm-workspace.yaml 组织多包），@tanstack/solid-query通过"@tanstack/query-core": "workspace:*"与核心包保持同步发布，安装时无需手工维护两者版本对齐。

何时需要额外安装 Devtools

examples/solid/simple/package.json 显示，调试工具是独立发布的包：

npm i @tanstack/solid-query @tanstack/solid-query-devtools

只有在调试阶段需要可视化面板时，才需要安装@tanstack/solid-query-devtools（其源码位于 packages/solid-query-devtools）。生产构建中无需引入它，以减小打包体积。

三、不使用打包器：通过 ESM CDN 引入

如果你正在写一个不使用模块打包器或包管理器的静态页面，官方文档给出了一种替代方案：通过 ESM 兼容的 CDN（如 ESM.sh）直接加载。

只需在 HTML 文件的</body>之前添加<script type="module">标签：

<script type="module"> import { QueryClient } from 'https://esm.sh/@tanstack/solid-query' </script>

使用要点

必须使用type="module"，因为该方案基于原生 ESM 加载，不支持传统同步<script>；
import { QueryClient }只是最小验证示例；在真实使用中你还需要从同一 CDN 引入solid-js、solid-js/web，并配合QueryClientProvider、useQuery等构建完整应用；
CDN 路径默认解析为最新稳定版；如需锁定版本，可写成形如https://esm.sh/@tanstack/solid-query@5.102.8的显式版本地址，保证缓存与行为可复现；
该方法同样适用于 CodePen、JSFiddle 等在线片段演示场景，适合"先跑起来再下载到本地工程"。

四、浏览器兼容要求（Requirements）

Solid Query 针对现代浏览器做了优化。官方在安装文档中声明了以下兼容配置：

Chrome >= 91 Firefox >= 90 Edge >= 91 Safari >= 15 iOS >= 15 Opera >= 77

老浏览器与旧环境怎么办

文档给出了两条明确指引，需要认真执行：

按需补充 polyfill：取决于你的目标环境，可能需要为缺失的 Web API 添加 polyfill（例如较老浏览器中不存在AbortController、queueMicrotask等与请求取消、调度相关的实现）；
自行转译库代码：如果你想支持上述范围之外更老的浏览器，需要把库从node_modules中一起纳入转译。绝大多数构建器（Vite、Webpack、Rollup）默认不转译node_modules，因此需要显式配置对该包放行。

配套的工程级校验手段

本仓库的 SDK 自身也在持续做多版本 TypeScript 兼容性验证：packages/solid-query/package.json 的test:types脚本会并行在 TS 5.6~5.9 与 7.0 等多个编译器版本下构建类型声明。这意味着：只要你的工程 TypeScript 版本处于合理范围内，一般不会因类型定义不兼容而阻断安装使用。若你本地构建遇到浏览器目标相关告警，优先检查tsconfig的target/lib以及 Vite 的build.target是否落在这份兼容表之内。

五、安装完成后如何快速验证：跑通官方 simple 示例

文档在结尾处提示：动手前想先体验，可尝试 simple 或 basic 示例（这两个链接指向的实例如下，仓库内路径均已以根目录为基准给出）：

examples/solid/simple — 最小可运行示例，只含一个数据请求查询；
examples/solid/basic — 稍完整的入门示例。

以 simple 为例，它的 package.json 依赖为@tanstack/solid-query、@tanstack/solid-query-devtools与solid-js，并使用vite+vite-plugin-solid驱动。其核心入口 src/index.tsx 展示了安装完成后最典型的装配链路：

import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/solid-query' import { SolidQueryDevtools } from '@tanstack/solid-query-devtools' import { Match, Switch } from 'solid-js' import { render } from 'solid-js/web' const queryClient = new QueryClient() function Example() { const state = useQuery(() => ({ queryKey: ['repoData'], queryFn: async () => { const response = await fetch('https://api.github.com/repos/TanStack/query') return await response.json() }, })) return ( <Switch> <Match when={state.isPending}>Loading...</Match> <Match when={state.error}> {'An error has occurred: ' + (state.error as Error).message} </Match> <Match when={state.data !== undefined}> <div>{/* 渲染仓库名称、描述、star/fork 等数据 */}</div> </Match> </Switch> ) } render( () => ( <QueryClientProvider client={queryClient}> <SolidQueryDevtools /> <Example /> </QueryClientProvider> ), document.getElementById('root')!, )

这个示例恰好验证了安装后的四项关键能力：

Provider 装配：QueryClientProvider将全局QueryClient注入组件树；
查询原语：useQuery接收返回{ queryKey, queryFn }的函数（Solid 风格响应式查询）；
状态分支渲染：利用state.isPending/state.error/state.data三个信号化字段配合Switch/Match渲染加载、错误与成功三种 UI；
Devtools 可插拔：SolidQueryDevtools仅在需要调试时引入。

在示例目录内执行pnpm install后运行pnpm dev（vite）即可看到真实请求效果，这也是对新装环境（网络、Peer 依赖解析、Node 版本）最直接的冒烟测试。

六、源码层面的再印证：安装后你会拿到什么

安装完成后，你实际消费的 API 入口可从 packages/solid-query/src/index.ts 的导出清单确认（索引、查询、无限查询、变更、状态订阅与 Provider 均在列）。与此同时，packages/solid-query/README.md 汇总了该包开箱即用的能力矩阵，包括：

与传输协议/后端无关的数据获取（REST、GraphQL、Promise 等）；
自动缓存与重取（stale-while-revalidate、窗口聚焦刷新、轮询/实时）；
并行与依赖查询、Mutation 与响应式重取；
多层缓存与自动垃圾回收；
分页/游标查询、加载更多与无限滚动查询及滚动位置恢复；
请求取消、Suspense 与 Fetch-As-You-Render 预取。

这些能力并非安装后自动生效的魔法，而是由@tanstack/query-core提供核心引擎、由@tanstack/solid-query以 Solid 响应式原语封装。理解这一点，在排查问题时就能区分"查询引擎行为"与"Solid 集成行为"两类故障面。

七、安装排错小贴士（基于仓库配置推断）

结合 packages/solid-query/package.json 与示例工程配置，整理几个常见安装/运行问题的自查方向：

Peer 依赖告警：确认solid-js版本满足^1.6.0的 peer 要求，examples/solid/*示例中使用的是solid-js@^1.9.7；
解析入口告警：包同时提供 ESM/CJS 与development条件导出，若构建器出现双包实例或 dev 产物误入生产构建的告警，请检查该工具对exports条件导出的支持程度；
浏览器目标过低：若运行环境低于官方兼容表（Chrome 91 / Firefox 90 / Edge 91 / Safari 15 等），按前文指引补充 polyfill 并放行对node_modules的转译；
类型环境不匹配：若 TS 编译报类型错误，先核对工程的 TypeScript 版本是否过于陈旧，仓库 CI 覆盖的 TypeScript 版本范围较广，过旧编译器（早于 5.6）可能需要升级。

综上，Solid Query 的安装链路非常清晰：现代浏览器项目直接选择任一包管理器安装 @tanstack/solid-query，调试场景追加 @tanstack/solid-query-devtools，无构建工具场景走 ESM.sh CDN，需要支持旧浏览器时做好 polyfill 与node_modules转译放行。如需完整参考，可对照安装文档及 examples/solid 下的示例逐项实操。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考