# npm
npm install swr
 
# pnpm（推荐）
pnpm add swr
 
# yarn
yarn add swr

import { SWRConfig } from 'swr'
 
export default function App() {
  return (
    <SWRConfig
      value={{
        // 请求失败后重试 3 次
        errorRetryCount: 3,
        // 窗口获焦时重新验证
        revalidateOnFocus: true,
        // 网络恢复时重新验证
        revalidateOnReconnect: true,
        // 数据过期时重新验证
        revalidateIfStale: true,
        // 全局 fetcher
        fetcher: (url: string) => fetch(url).then(res => res.json()),
        // 全局 Suspense 配置
        suspense: false,
      }}
    >
      <YourApp />
    </SWRConfig>
  )
}

useSWR('/api/user', fetcher, {
  revalidateOnFocus: false,
  refreshInterval: 5000,
})

'use client'
 
import useSWR from 'swr'
 
// 全局 fetcher
const fetcher = (url: string) => fetch(url).then(res => res.json())
 
function Profile() {
  const { data, error, isLoading } = useSWR('/api/user/123', fetcher)
 
  // 加载中状态
  if (isLoading) return <div>加载中...</div>
 
  // 错误状态
  if (error) return <div>加载失败：{error.message}</div>
 
  // 成功状态
  return <div>用户名：{data.name}</div>
}

// 只有 userId 存在时才发起请求
const { data } = useSWR(userId ? `/api/user/${userId}` : null, fetcher)

import { SWRConfig } from 'swr'
import { useState } from 'react'
 
function App() {
  const [cache] = useState(() => new Map())
 
  return (
    <SWRConfig value={{ provider: () => cache }}>
      <YourApp />
    </SWRConfig>
  )
}

// 窗口获焦时自动重新验证
const { data } = useSWR('/api/notifications', fetcher)

// 三个组件使用相同 key，只会发一次请求
function Header() {
  const { data: user } = useSWR('/api/user', fetcher)
  // ...
}
function Sidebar() {
  const { data: user } = useSWR('/api/user', fetcher)
  // ...
}

import useSWR, { mutate } from 'swr'
 
function TodoList() {
  const { data, mutate } = useSWR('/api/todos', fetcher)
 
  const addTodo = async (todo) => {
    // 乐观更新：先更新 UI，再发请求
    mutate(
      [...(data || []), todo],
      false // 不重新验证
    )
 
    // 发送请求
    await fetch('/api/todos', {
      method: 'POST',
      body: JSON.stringify(todo)
    })
 
    // 重新验证
    mutate()
  }
}

const { data } = useSWR('/api/stats', fetcher, {
  refreshInterval: 1000, // 每秒轮询
  refreshWhenHidden: false, // 页面隐藏时暂停
  refreshWhenOffline: false, // 离线时暂停
})

import { Suspense } from 'react'
import useSWR from 'swr'
 
function Data() {
  const { data } = useSWR('/api/data', fetcher, { suspense: true })
  return <div>{data.title}</div>
}
 
function Page() {
  return (
    <Suspense fallback={<div>加载中...</div>}>
      <Data />
    </Suspense>
  )
}

import useSWRMutation from 'swr/mutation'
 
async function addComment(url, { arg }: { arg: Comment }) {
  const res = await fetch(url, {
    method: 'POST',
    body: JSON.stringify(arg)
  })
  return res.json()
}
 
function CommentList() {
  const { data, trigger } = useSWRMutation('/api/comments', addComment)
 
  const handleSubmit = (newComment: Comment) => {
    trigger(newComment, {
      optimisticData: (current) => [...(current || []), newComment],
      rollbackOnError: true,
      populateCache: true,
      revalidate: false,
    })
  }
}

import useSWRInfinite from 'swr/infinite'
 
function UserList() {
  const { data, size, setSize, isLoadingMore, isReachingEnd } = useSWRInfinite(
    (index, previousPageData) => {
      if (previousPageData && !previousPageData.hasMore) return null
      return `/api/users?page=${index}`
    },
    fetcher
  )
 
  return (
    <div>
      {data?.map((users) =>
        users.map((user) => <UserCard key={user.id} user={user} />)
      )}
      <button
        onClick={() => setSize(size + 1)}
        disabled={isReachingEnd || isLoadingMore}
      >
        {isLoadingMore ? '加载中...' : isReachingEnd ? '没有更多' : '加载更多'}
      </button>
    </div>
  )
}

import useSWRSubscription from 'swr/subscription'
 
function StockPrice() {
  const { data, error } = useSWRSubscription(
    '/api/stock/AAPL',
    (key, { next }) => {
      const ws = new WebSocket(`wss://stocks.example.com/${key}`)
      ws.onmessage = (event) => next(null, JSON.parse(event.data))
      ws.onerror = (e) => next(e, null)
      return () => ws.close()
    }
  )
 
  if (error) return <div>连接失败</div>
  return <div>当前价格：${data?.price}</div>
}

import { preload } from 'swr'
 
// 鼠标悬停时预加载下一页
<Link
  href="/dashboard"
  onMouseEnter={() => preload('/api/dashboard', fetcher)}
  onFocus={() => preload('/api/dashboard', fetcher)}
>
  进入仪表盘
</Link>

import useSWRImmutable from 'swr/immutable'
 
// 只请求一次，永不重新验证
const { data } = useSWRImmutable('/api/archive/2024', fetcher)

// App Router + Server Component 预取 + Client Component 使用 SWR
import { SWRConfig, unstable_serialize } from 'swr'
 
export default async function Page() {
  const data = await fetchUser()
  return (
    <SWRConfig value={{ fallback: { [unstable_serialize('/api/user')]: data } }}>
      <UserProfile />
    </SWRConfig>
  )
}

// 仪表盘数据每秒刷新
const { data } = useSWR('/api/dashboard', fetcher, {
  refreshInterval: 1000,
  revalidateOnFocus: true,
})

const [query, setQuery] = useState('')
const { data, isLoading } = useSWR(
  `/api/search?q=${query}`,
  fetcher,
  { keepPreviousData: true, dedupingInterval: 300 }
)

const { trigger, isMutating } = useSWRMutation('/api/comments', addComment)
 
// 用户点击提交后，评论立即出现在列表中（乐观更新）
await trigger(newComment, {
  optimisticData: (data) => [...data, newComment],
  rollbackOnError: true,
})

const { data, size, setSize } = useSWRInfinite(getKey, fetcher)

interface User {
  id: number
  name: string
  email: string
}
 
// 泛型推断 data 类型为 User | undefined
const { data, error } = useSWR<User>('/api/user/1', fetcher)
 
// 自定义 fetcher 类型
const fetcher = async (url: string): Promise<User> => {
  const res = await fetch(url)
  if (!res.ok) throw new Error('Failed to fetch')
  return res.json()
}

const { data, error, isLoading } = useSWR('/api/data', fetcher, {
  onError: (error, key) => {
    console.error(`请求 ${key} 失败:`, error)
  },
  onErrorRetry: (error, key, config, revalidate, { retryCount }) => {
    // 404 不重试
    if (error.status === 404) return
    // 最多重试 3 次
    if (retryCount >= 3) return
    // 5 秒后重试
    setTimeout(() => revalidate({ retryCount }), 5000)
  },
})
 
if (error) {
  return <ErrorMessage error={error} />
}

import { render, screen } from '@testing-library/react'
import useSWR from 'swr'
import { SWRConfig } from 'swr'
 
// 使用 SWRConfig 提供测试数据
function TestProvider({ children, fallback }: { children: React.ReactNode; fallback: Record<string, any> }) {
  return (
    <SWRConfig value={{ provider: () => new Map(), fallback }}>
      {children}
    </SWRConfig>
  )
}
 
test('renders user data from cache', () => {
  render(<Profile />, {
    wrapper: ({ children }) => (
      <TestProvider fallback={{ '/api/user': { name: '测试用户' } }}>
        {children}
      </TestProvider>
    ),
  })
  expect(screen.getByText('测试用户')).toBeInTheDocument()
})

# 在根目录安装（workspace 共享）
pnpm add swr -w
 
# 或在具体 app 中安装
pnpm --filter @my-app/web add swr

// 只导入需要的 hooks
import useSWR from 'swr'
import useSWRMutation from 'swr/mutation'
// useSWRInfinite 和 useSWRSubscription 不导入，不参与打包

const { data } = useSWR('/api/user', fetcher, {
  dedupingInterval: 2000, // 2 秒内的相同请求去重
})

const { data } = useSWR(isLoggedIn ? '/api/user' : null, fetcher)

// 在路由切换前预加载
router.prefetch('/dashboard')
preload('/api/dashboard', fetcher)

const { data } = useSWR('/api/data', fetcher, {
  revalidateOnFocus: false, // 避免频繁切换标签页时的请求风暴
})

const fetcher = async (url: string) => {
  const res = await fetch(url, {
    credentials: 'include', // 携带 Cookie
    headers: {
      'X-CSRF-Token': getCsrfToken(), // CSRF 防护
    },
  })
  if (!res.ok) throw new Error(`HTTP ${res.status}`)
  return res.json()
}

// ✅ 好的 key 设计：包含所有影响数据的参数
const { data } = useSWR(`/api/users?page=${page}&sort=${sort}`, fetcher)
 
// ✅ 数组 key：自动参与依赖追踪
const { data } = useSWR(['/api/users', page, sort], ([url, page, sort]) =>
  fetch(`${url}?page=${page}&sort=${sort}`).then(r => r.json())
)
 
// ❌ 避免：key 中包含随机值或时间戳
const { data } = useSWR(`/api/data?t=${Date.now()}`, fetcher) // 每次都会重新请求

// ✅ 正确：使用 isLoading 区分首次加载
const { data, error, isLoading } = useSWR('/api/user', fetcher)
 
if (isLoading) return <Spinner /> // 首次加载
if (error) return <Error error={error} />
return <UserData data={data} />
 
// ❌ 错误：!data 无法区分"无数据"和"加载中"
if (!data) return <Spinner /> // 也可能 data 为 null/undefined 的正常情况

const { data, mutate } = useSWR('/api/todos', fetcher)
 
const deleteTodo = async (id: string) => {
  const originalData = data
 
  // 乐观删除
  mutate(data.filter((t) => t.id !== id), false)
 
  try {
    await fetch(`/api/todos/${id}`, { method: 'DELETE' })
    mutate() // 重新验证
  } catch (error) {
    // 回滚
    mutate(originalData, false)
  }
}

import { mutate } from 'swr'
 
// 清除所有用户相关缓存
mutate(
  (key) => typeof key === 'string' && key.startsWith('/api/users'),
  undefined,
  { revalidate: false }
)

'use client'
 
import useSWR from 'swr'
import { mutate } from 'swr'
 
export function CommentList() {
  const { data: comments } = useSWR('/api/comments', fetcher)
 
  return (
    <ul>
      {comments?.map((c) => <li key={c.id}>{c.text}</li>)}
    </ul>
  )
}
 
export function CommentForm() {
  const addComment = async (formData: FormData) => {
    'use server'
    const text = formData.get('text')
    await db.comments.create({ text })
    // Server Action 执行后，重新验证评论列表
    mutate('/api/comments')
  }
 
  return (
    <form action={addComment}>
      <input name="text" />
      <button type="submit">提交</button>
    </form>
  )
}

'use client'
 
import { preload } from 'swr'
import Link from 'next/link'
 
function NavItem({ href, children }: { href: string; children: React.ReactNode }) {
  return (
    <Link
      href={href}
      onMouseEnter={() => preload(`/api/page/${href}`, fetcher)}
      onFocus={() => preload(`/api/page/${href}`, fetcher)}
    >
      {children}
    </Link>
  )
}

import { ErrorBoundary } from 'react-error-boundary'
import { Suspense } from 'react'
import useSWR from 'swr'
 
function DataComponent() {
  const { data } = useSWR('/api/data', fetcher, {
    suspense: true, // 抛出 Promise 给 Suspense
  })
  return <div>{data.title}</div>
}
 
function Page() {
  return (
    <ErrorBoundary fallback={<div>出错了</div>}>
      <Suspense fallback={<div>加载中...</div>}>
        <DataComponent />
      </Suspense>
    </ErrorBoundary>
  )
}

import { SWRConfig } from 'swr'
import { useState } from 'react'
 
export function App() {
  // 使用 Map 作为缓存提供者，提升性能
  const [cache] = useState(() => new Map())
 
  return (
    <SWRConfig
      value={{
        provider: () => cache,
        // 清理策略（配合页面可见性）
        isVisible: () => document.visibilityState === 'visible',
      }}
    >
      <YourApp />
    </SWRConfig>
  )
}

// 需要自行集成 localStorage / IndexedDB
import localforage from 'localforage'
 
const persistentFetcher = async (key: string) => {
  // 先尝试从 IndexedDB 读取
  const cached = await localforage.getItem(key)
  if (cached) return cached
 
  // 否则从网络获取
  const data = await fetch(key).then(r => r.json())
  await localforage.setItem(key, data)
  return data
}

// Server Action 处理后刷新 SWR 缓存
import { mutate } from 'swr'
 
async function updateProfile(formData: FormData) {
  'use server'
  await db.users.update(/* ... */)
  mutate('/api/profile') // 通知 SWR 重新验证
}