如何使用 Cache Components 实现身份验证
了解在启用 Cache Components 时,如何读取用户会话、在不拖慢页面的情况下显示经过身份验证的 UI,以及缓存从会话派生的数据。
启用 Cache Components后,会话读取发生在请求时,因此无法预渲染到静态外壳中。经过身份验证的 UI 会在 <Suspense> 边界后流式传入,而从会话派生的数据仍然可以被缓存。
这些示例使用 iron-session 来实现加密的 cookie 会话,但这些模式适用于任何会话或身份验证库。如需完整可运行的版本,请参阅 with-iron-session-cache-components 示例。
先决条件#
启用 cacheComponents:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig本指南介绍使用 Cache Components 进行身份验证的代码模式:在请求时读取会话、流式传输经过身份验证的 UI,以及缓存会话派生的数据。它假定你已熟悉 Cache Components(如果不熟悉,请先阅读缓存),并且你已经在登录时设置了会话。
对于本指南所依赖的基础知识,我们推荐两篇指南:
迁移现有应用#
启用 Cache Components 后,即时导航验证会标记每个读取会话的路由,因为请求读取无法预渲染到静态外壳中。你不必在发布前解决所有问题。在页面或布局上设置 export const instant = false,使其继续在服务器上阻塞,然后逐条路由采用下面的模式。有关完整的迁移工作流程,请参阅迁移到 Cache Components。
第 1 步:读取当前用户#
读取当前用户会先读取会话 cookie,然后查找用户。请求读取不能成为静态外壳的一部分,因此它始终位于 <Suspense>边界之后,并在每次导航时流式传入。
由于用户会话在一段时间内有效,添加缓存生存期可让框架提前预取该内容。
不过,服务器端指令无法提供该生存期:普通的 use cache 和 use cache: remote 都不能调用 cookies(),你也不能提取该值并传入,原因是:
- 会话辅助函数在其代码深处读取 cookie,因此没有可提取的内容。
- 验证它需要将令牌的过期时间与当前时间进行比较(iron-session 的
unsealData会拒绝已过期的封装),因此该读取依赖于请求和时间。
这正是 use cache: private 的用途:它直接读取 cookies() 和 headers(),并将结果仅保留在浏览器中,绝不会保留在服务器上。
私有作用域保留在浏览器中,因此绝不会在服务器上缓存。若要改为在服务器上缓存,请提取一个值(例如 userId),并将其传入普通的 use cache 或 use cache: remote。相同的模式也可用于缓存会话派生的数据,详见第 4 步。
import 'server-only'
import { cookies } from 'next/headers'
import { sealData, unsealData } from 'iron-session'
export type SessionData = {
userId?: string
}
const COOKIE_NAME = 'app_session'
const password = process.env.SESSION_PASSWORD!
export async function getSession(): Promise<SessionData> {
const cookie = (await cookies()).get(COOKIE_NAME)?.value
if (!cookie) {
return {}
}
return unsealData<SessionData>(cookie, { password })
}import 'server-only'
import { redirect } from 'next/navigation'
import { getSession } from './session'
import { findUserById } from './data'
export type User = {
id: string
name: string
}
export async function getCurrentUser(): Promise<User> {
'use cache: private'
const { userId } = await getSession()
if (!userId) {
redirect('/login')
}
const user = await findUserById(userId)
if (!user) {
redirect('/login')
}
return { id: user.id, name: user.name }
}redirect() 调用会抛出异常以中断渲染,而不是返回值,因此它们不会被缓存。只有成功解析出的用户才会被缓存。
小知识:
use cache: private接受cookies()、headers()和searchParams,但不接受connection()。完整列表请参阅use cache: private。
第 2 步:显示用户而不阻塞页面#
读取会话的组件必须位于 <Suspense>边界之后。使用 Cache Components 时,在边界之外读取 cookies() 会导致构建错误。该边界也是保持页面其余部分快速的原因。边界之外的任何内容都会预渲染到静态外壳中并即时加载,只要它是静态的,或被包裹在 use cache 中并且不读取自身的运行时数据。只有边界之后的部分会等待请求。
import { Suspense } from 'react'
import { getCurrentUser } from '@/lib/auth'
import { getAnnouncements } from '@/lib/data'
export default function Page() {
return (
<main>
<Announcements />
<Suspense fallback={<p>Loading your dashboard…</p>}>
<Dashboard />
</Suspense>
</main>
)
}
async function Announcements() {
'use cache'
const announcements = await getAnnouncements()
return (
<ul>
{announcements.map((announcement) => (
<li key={announcement}>{announcement}</li>
))}
</ul>
)
}
async function Dashboard() {
const user = await getCurrentUser()
return <h1>Welcome, {user.name}</h1>
}同样,也不要在布局的顶层读取会话。在布局中对会话进行顶层 await 会使整个段(包括 {children})都被该请求阻塞,因此应将其下移到边界内的组件中。请参阅下移动态访问。
小知识:
getCurrentUser会读取会话、对其进行检查,并返回一个精简的用户对象。将这些读取集中在一个函数中就是数据访问层模式。
第 3 步:在组件之间共享用户#
你不必在每个需要用户的组件中都重新读取会话。只需读取一次,然后在同一边界内将其传递给任意数量的 Server Component 和 Client Component。
Server Component 可以直接调用 getCurrentUser()。若要将用户传递到 Client Component 而无需层层传递 props,可创建一次 promise,通过 context 传递它,并使用 use() 解包。有关通用模式,请参阅在 Context Provider 中使用 React 的 use。由于 getCurrentUser 会读取请求,请在 Suspense 边界内创建其 promise,而不是在布局的顶层。
'use client'
import { createContext, use } from 'react'
import type { ReactNode } from 'react'
import type { User } from '@/lib/auth'
const UserContext = createContext<Promise<User> | null>(null)
export function UserProvider({
userPromise,
children,
}: {
userPromise: Promise<User>
children: ReactNode
}) {
return <UserContext value={userPromise}>{children}</UserContext>
}
export function useUser() {
const userPromise = use(UserContext)
if (!userPromise) {
throw new Error('useUser must be used within a UserProvider')
}
return use(userPromise)
}边界后的 Server Component 创建 promise 并将其传递给 provider,而无需等待它。然后,每个使用者在自己的边界后解析它,因此共享的框架内容无需等待会话即可渲染:
function Dashboard() {
const userPromise = getCurrentUser()
return (
<UserProvider userPromise={userPromise}>
<Suspense fallback={<span>Loading…</span>}>
<UserBadge />
</Suspense>
</UserProvider>
)
}Client Component 调用 useUser() 来获取当前用户。由于 use() 会一直挂起直到 promise 解析,因此请将组件保持在 <Suspense> 边界之后:
'use client'
import { useUser } from './user-provider'
export function UserBadge() {
const user = useUser()
return <span>Signed in as {user.name}</span>
}小知识: 只暴露客户端需要的内容。
getCurrentUser辅助函数返回的是精简的{ id, name },而不是原始会话。要防止敏感字段到达客户端,请参阅taintUniqueValue。
第 4 步:缓存会话派生的数据#
有了用户之后,你可以用两种方式缓存为其获取的数据。将用户 id 传入普通的 use cache 函数会将结果保留在服务器上,并以该 id 作为键(它成为缓存键的一部分),之后 cacheTag 可以使其失效。在 use cache: private 作用域内读取它会将其仅保留在浏览器中,绝不在服务器上保留,当需求禁止在服务器端(即使是临时)存储某些数据时,这一点很重要。本示例传递的是 id,因为这些笔记带有标签,会在变化时刷新。
普通的 use cache 作用域无法读取 cookies(),因此导出的函数会解析用户,并仅将 id 传递给被缓存的函数:
import 'server-only'
import { cacheLife, cacheTag } from 'next/cache'
import { getCurrentUser } from './auth'
export async function getNotes() {
const user = await getCurrentUser()
return getNotesByUserId(user.id)
}
async function getNotesByUserId(userId: string) {
'use cache'
cacheTag(`notes:${userId}`)
cacheLife('minutes')
return db.query.notes.findMany({
where: (notes, { eq }) => eq(notes.userId, userId),
})
}不要导出 getNotesByUserId,以免调用方通过传入不同的 id 来请求其他用户的笔记。在导出的 getter 中解析用户正是保证其安全的原因。请参阅数据安全。
从渲染笔记的 Server Component 中调用它。无需传递用户 id,并且 getter 内部的 getCurrentUser() 调用会命中私有缓存,因此不会再次读取会话:
async function Notes() {
const notes = await getNotes()
// ...
}小知识:缓存键和标签以纯文本形式存储。 被缓存函数的参数和捕获的变量会被序列化到其缓存键中,
cacheTag的值按原样存储。两者都不会被哈希:默认缓存将它们保存为纯文本的映射键和标签列表,远程缓存也以相同方式接收它们。请使用像用户 id 这样的稳定标识符作为键和标签,并避免将机密和敏感个人数据(令牌、密码、原始电子邮件)放入参数和标签中。
在服务器上,普通的 use cache 会尽最大努力将条目保留在内存中:在内存压力下它会被逐出,并且在无服务器环境中不会跨实例持久存在。如果这些数据必须跨实例和请求保留,请选择 use cache: remote以获得持久的共享存储,在这种情况下,你选择的缓存键决定了命中率。
第 5 步:更新会话派生的数据#
当 Server Action 更改用户数据时,使用相同的标签调用 updateTag 以刷新缓存条目。请在 action 内部重新读取会话,使其自行授权,而不是信任客户端。有关为何这样做很重要,请参阅使用 Server Action 进行身份验证。
'use server'
import { redirect } from 'next/navigation'
import { updateTag } from 'next/cache'
import { getSession } from '@/lib/session'
import { saveNote } from '@/lib/data'
export async function addNote(formData: FormData) {
const { userId } = await getSession()
if (!userId) {
redirect('/login')
}
const note = String(formData.get('note') ?? '').trim()
if (note) {
await saveNote(userId, note)
updateTag(`notes:${userId}`)
}
}第 6 步:让经过身份验证的导航即时化#
缓存读取本身已有生存期,因此这大多会自动实现。除非你进行设置,否则 use cache: private 作用域使用 default 配置(五分钟的 stale),而读取会话的路由会生成一个包含经过身份验证内容的按会话划分的 App Shell,并按会话进行预取和缓存。对它的导航已经是即时的。
有两件事可以保持这种状态:
- 如果你使用
cacheLife调整生存期,请将stale保持在 30 秒或以上。低于该值,该作用域将退出预取。请参阅cacheLife客户端缓存行为。 - 如果路由还依赖 URL(
params或searchParams值),则需要在指向它的链接上使用<Link prefetch={true}>。这会选择按链接预取,从而在点击前解析按链接的数据。
<Link href={`/notes/${note.id}`} prefetch={true}>
{note.text}
</Link>目标路由需要部分预取才能实现这一点,因此请启用 partialPrefetching 标志,或在段上设置 prefetch = 'partial'。只在值得等待的地方添加该 prop:这种预取会为每个链接产生一次服务器调用,因此一个包含 /chat/[id] 链接的侧边栏会为每一项付出该成本。
常见陷阱#
- 在普通的
use cache函数内读取cookies()或headers()。 这会抛出异常。请在外部读取请求并传入值,或使用use cache: private。 - 将机密或个人数据放入缓存键或标签中。 参数和
cacheTag值以纯文本形式存储。请使用稳定的标识符作为键和标签,而不是敏感输入。 - 信任客户端进行授权。 UI 检查只是隐藏元素,但并不能保护数据。请在每个 Server Action 和 Route Handler中重新验证会话,并尽可能靠近数据。请参阅授权。