Single-Page Applications with Next.js

Next.js 完全支持构建单页应用（SPAs）。

这包括使用预取实现快速路由转换、客户端数据获取、使用浏览器 API、集成第三方客户端库、创建静态路由等。

如果你已有一个 SPA，你可以迁移到 Next.js 而无需对代码进行大量更改。然后，Next.js 允许你根据需要逐步添加服务器功能。

什么是单页应用？

SPA 的定义各不相同。我们将"严格 SPA"定义为：

客户端渲染（CSR）：应用通过一个 HTML 文件（例如 index.html）提供服务。每个路由、页面转换和数据获取都由浏览器中的 JavaScript 处理。
无完整页面刷新：不是为每个路由请求新文档，而是由客户端 JavaScript 操作当前页面的 DOM 并根据需要获取数据。

严格的 SPA 通常需要加载大量 JavaScript 才能使页面具有交互性。此外，客户端数据瀑布流可能难以管理。使用 Next.js 构建 SPA 可以解决这些问题。

为什么使用 Next.js 构建 SPA？

Next.js 可以自动对 JavaScript 包进行代码拆分，并为不同路由生成多个 HTML 入口点。这避免了在客户端加载不必要的 JavaScript 代码，减小了包的大小并实现了更快的页面加载。

next/link 组件会自动预取路由，提供严格 SPA 的快速页面转换，同时还有将应用路由状态保存到 URL 以便链接和共享的优势。

Next.js 可以从静态站点甚至是完全在客户端渲染的严格 SPA 开始。如果你的项目发展壮大，Next.js 允许你根据需要逐步添加更多服务器功能（例如 React Server Components、Server Actions 等）。

示例

让我们探讨用于构建 SPA 的常见模式以及 Next.js 如何解决它们。

在 Context Provider 中使用 React 的 `use`

我们建议在父组件（或布局）中获取数据，返回 Promise，然后使用 React 的 use 钩子在客户端组件中解包该值。

Next.js 可以在服务器上提前开始数据获取。在这个例子中，这是根布局——应用的入口点。服务器可以立即开始向客户端流式传输响应。

通过将数据获取"提升"到根布局，Next.js 会在应用中的任何其他组件之前在服务器上提前开始指定的请求。这消除了客户端瀑布流，并防止了客户端和服务器之间的多次往返。它还可以显著提升性能，因为你的服务器离数据库所在位置更近（理想情况下是同一位置）。

例如，更新你的根布局以调用 Promise，但不要等待它。

app/layout.tsx

TypeScript

import { UserProvider } from './user-provider'
import { getUser } from './user' // some server-side function
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  let userPromise = getUser() // do NOT await
 
  return (
    <html lang="en">
      <body>
        <UserProvider userPromise={userPromise}>{children}</UserProvider>
      </body>
    </html>
  )
}

虽然你可以延迟并将单个 Promise 作为 prop 传递给客户端组件，但我们通常看到这种模式与 React context provider 一起使用。这通过自定义 React hook 实现了更容易从客户端组件访问。

你可以将 Promise 转发给 React context provider：

app/user-provider.ts

TypeScript

'use client';
 
import { createContext, useContext, ReactNode } from 'react';
 
type User = any;
type UserContextType = {
  userPromise: Promise<User | null>;
};
 
const UserContext = createContext<UserContextType | null>(null);
 
export function useUser(): UserContextType {
  let context = useContext(UserContext);
  if (context === null) {
    throw new Error('useUser must be used within a UserProvider');
  }
  return context;
}
 
export function UserProvider({
  children,
  userPromise
}: {
  children: ReactNode;
  userPromise: Promise<User | null>;
}) {
  return (
    <UserContext.Provider value={{ userPromise }}>
      {children}
    </UserContext.Provider>
  );
}

最后，你可以在任何客户端组件中调用 useUser() 自定义 hook 并解包 Promise：

app/profile.tsx

TypeScript

'use client'
 
import { use } from 'react'
import { useUser } from './user-provider'
 
export function Profile() {
  const { userPromise } = useUser()
  const user = use(userPromise)
 
  return '...'
}

消费 Promise 的组件（例如上面的 Profile）将被暂停。这实现了部分水合。你可以在 JavaScript 加载完成之前看到流式传输和预渲染的 HTML。

使用 SWR 的 SPA

SWR 是一个流行的 React 数据获取库。

使用 SWR 2.3.0（和 React 19+），你可以在现有的基于 SWR 的客户端数据获取代码旁边逐步采用服务器功能。这是上述 use() 模式的抽象。这意味着你可以在客户端和服务器端之间移动数据获取，或者同时使用两者：

仅客户端： useSWR(key, fetcher)
仅服务器： useSWR(key) + RSC 提供的数据
混合： useSWR(key, fetcher) + RSC 提供的数据

例如，用 <SWRConfig> 和 fallback 包装你的应用：

app/layout.tsx

TypeScript

import { SWRConfig } from 'swr'
import { getUser } from './user' // some server-side function
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <SWRConfig
      value={{
        fallback: {
          // We do NOT await getUser() here
          // Only components that read this data will suspend
          '/api/user': getUser(),
        },
      }}
    >
      {children}
    </SWRConfig>
  )
}

因为这是一个服务器组件，getUser() 可以安全地读取 cookies、headers 或与你的数据库通信。不需要单独的 API 路由。<SWRConfig> 下的客户端组件可以使用相同的键调用 useSWR() 来检索用户数据。带有 useSWR 的组件代码不需要任何更改，与你现有的客户端获取解决方案相同。

app/profile.tsx

TypeScript

'use client'
 
import useSWR from 'swr'
 
export function Profile() {
  const fetcher = (url) => fetch(url).then((res) => res.json())
  // The same SWR pattern you already know
  const { data, error } = useSWR('/api/user', fetcher)
 
  return '...'
}

fallback 数据可以预渲染并包含在初始 HTML 响应中，然后使用 useSWR 在子组件中立即读取。SWR 的轮询、重新验证和缓存仍然仅在客户端运行，因此它保留了你依赖的 SPA 所有交互性。

由于初始 fallback 数据由 Next.js 自动处理，你现在可以删除之前需要的任何条件逻辑来检查 data 是否为 undefined。当数据正在加载时，最近的 <Suspense> 边界将被暂停。

	SWR	RSC	RSC + SWR
SSR 数据
SSR 期间的流式传输
请求去重
客户端功能

使用 React Query 的 SPA

你可以在客户端和服务器上都使用 React Query 与 Next.js。这使你能够构建严格的 SPA，以及利用 Next.js 中的服务器功能与 React Query 配合使用。

在 React Query 文档中了解更多。

仅在浏览器中渲染组件

客户端组件在 next build 期间被预渲染。如果你想为客户端组件禁用预渲染，只在浏览器环境中加载它，你可以使用 next/dynamic：

import dynamic from 'next/dynamic'
 
const ClientOnlyComponent = dynamic(() => import('./component'), {
  ssr: false,
})

这对依赖浏览器 API（如 window 或 document）的第三方库很有用。你还可以添加一个 useEffect 来检查这些 API 是否存在，如果不存在，则返回 null 或加载状态，这些将被预渲染。

客户端浅层路由

如果你正在从严格的 SPA（如 Create React App 或 Vite）迁移，你可能有现有代码使用浅层路由来更新 URL 状态。这对于在应用中手动进行视图间转换很有用，_无需_使用默认的 Next.js 文件系统路由。

Next.js 允许你使用原生的 window.history.pushState 和 window.history.replaceState 方法来更新浏览器的历史堆栈，而无需重新加载页面。

pushState 和 replaceState 调用集成到 Next.js 路由器中，允许你与 usePathname 和 useSearchParams 同步。

'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SortProducts() {
  const searchParams = useSearchParams()
 
  function updateSorting(sortOrder: string) {
    const urlSearchParams = new URLSearchParams(searchParams.toString())
    urlSearchParams.set('sort', sortOrder)
    window.history.pushState(null, '', `?${urlSearchParams.toString()}`)
  }
 
  return (
    <>
      <button onClick={() => updateSorting('asc')}>Sort Ascending</button>
      <button onClick={() => updateSorting('desc')}>Sort Descending</button>
    </>
  )
}

'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SortProducts() {
  const searchParams = useSearchParams()
 
  function updateSorting(sortOrder) {
    const urlSearchParams = new URLSearchParams(searchParams.toString())
    urlSearchParams.set('sort', sortOrder)
    window.history.pushState(null, '', `?${urlSearchParams.toString()}`)
  }
 
  return (
    <>
      <button onClick={() => updateSorting('asc')}>Sort Ascending</button>
      <button onClick={() => updateSorting('desc')}>Sort Descending</button>
    </>
  )
}

了解更多关于 Next.js 中路由和导航的工作原理。

在客户端组件中使用 Server Actions

你可以在使用客户端组件的同时逐步采用 Server Actions。这允许你删除调用 API 路由的样板代码，而是使用 React 功能如 useActionState 来处理加载和错误状态。

例如，创建你的第一个 Server Action：

app/actions.ts

TypeScript

'use server'
 
export async function create() {}

你可以从客户端导入并使用 Server Action，类似于调用 JavaScript 函数。你不需要手动创建 API 端点：

app/button.tsx

TypeScript

'use client'
 
import { create } from './actions'
 
export function Button() {
  return <button onClick={() => create()}>Create</button>
}

了解更多关于使用 Server Actions 修改数据。

静态导出（可选）

Next.js 还支持生成完全静态站点。这比严格的 SPA 有一些优势：

自动代码拆分：Next.js 不是提供单一的 index.html，而是为每个路由生成一个 HTML 文件，这样你的访问者无需等待客户端 JavaScript 包就能更快地获取内容。
改善用户体验：不是所有路由都使用最小骨架，而是为每个路由获取完全渲染的页面。当用户在客户端导航时，转换仍然是即时的，像 SPA 一样。

要启用静态导出，请更新你的配置：

next.config.ts

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  output: 'export',
}
 
export default nextConfig

运行 next build 后，Next.js 将创建一个包含应用 HTML/CSS/JS 资源的 out 文件夹。

注意： 静态导出不支持 Next.js 服务器功能。了解更多。

将现有项目迁移到 Next.js

你可以通过遵循我们的指南逐步迁移到 Next.js：

如果你已经使用 Pages Router 的 SPA，你可以了解如何逐步采用 App Router。