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

本文导读：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

老浏览器与旧环境怎么办

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

1. 按需补充 polyfill：取决于你的目标环境，可能需要为缺失的 Web API 添加 polyfill（例如较老浏览器中不存在 AbortController、queueMicrotask 等与请求取消、调度相关的实现）；
2. 自行转译库代码：如果你想支持上述范围之外更老的浏览器，需要把库从 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')!,
)

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

1. Provider 装配：QueryClientProvider 将全局 QueryClient 注入组件树；
2. 查询原语：useQuery 接收返回 { queryKey, queryFn } 的函数（Solid 风格响应式查询）；
3. 状态分支渲染：利用 state.isPending / state.error / state.data 三个信号化字段配合 Switch/Match 渲染加载、错误与成功三种 UI；
4. 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 下的示例逐项实操。