如何理解 Next.js 中的数据安全
了解 Next.js 内置的数据安全特性,以及保护应用数据的最佳实践。
React Server Components 提升了性能并简化了数据获取,但也改变了数据访问的位置和方式,改变了前端应用中处理数据的一些传统安全假设。
本指南将帮助你理解如何看待 Next.js 中的数据安全,以及如何实施最佳实践。
数据获取方式#
根据项目的规模和存在时间,我们推荐在 Next.js 中获取数据的主要方式有三种:
我们建议选择一种数据获取方式,避免混用。这让在你的代码库中工作的开发人员和安全审计人员都能清楚预期。
外部 HTTP API#
在现有项目中采用 Server Components 时,你应遵循零信任模型。你可以继续使用 fetch 从 Server Components 调用现有的 API 端点(如 REST 或 GraphQL),就像在 Client Components 中一样。
import { cookies } from 'next/headers'
export default async function Page() {
const cookieStore = await cookies()
const token = cookieStore.get('AUTH_TOKEN')?.value
const res = await fetch('https://api.example.com/profile', {
headers: {
Cookie: `AUTH_TOKEN=${token}`,
// 其他标头
},
})
// ....
}这种方式适用于以下情况:
- 你已经有了既定的安全实践。
- 独立的后端团队使用其他语言或独立管理 API。
数据访问层#
对于新项目,我们建议创建一个专用的数据访问层(Data Access Layer,DAL)。这是一个内部库,用于控制数据的获取方式和时机,以及传递到渲染上下文的内容。
数据访问层应该:
- 仅在服务器上运行。
- 执行授权检查。
- 返回安全、精简的数据传输对象(Data Transfer Objects,DTO)。
这种方式集中管理所有数据访问逻辑,使执行一致的数据访问变得更容易,并降低授权漏洞的风险。你还可以受益于在请求的不同部分之间共享内存缓存。
import { cache } from 'react'
import { cookies } from 'next/headers'
// 缓存的辅助方法使在多处获取相同值变得容易,
// 而无需手动传递。这避免了将其从 Server Component
// 传递到 Server Component,从而最大程度降低了将其
// 传递到 Client Component 的风险。
export const getCurrentUser = cache(async () => {
const cookieStore = await cookies()
const token = cookieStore.get('AUTH_TOKEN')
const decodedToken = await decryptAndValidate(token)
// 不要将秘密令牌或私有信息作为公共字段包含在内。
// 使用类以避免意外将整个对象传递给客户端。
return new User(decodedToken.id)
})import 'server-only'
import { getCurrentUser } from './auth'
function canSeeUsername(viewer: User) {
// 目前是公开信息,但可能会变化
return true
}
function canSeePhoneNumber(viewer: User, team: string) {
// 隐私规则
return viewer.isAdmin || team === viewer.team
}
export async function getProfileDTO(slug: string) {
// 不传递值,而是读回缓存的值,这也解决了上下文问题并更容易实现惰性化
// 使用支持安全查询模板的数据库 API
const [rows] = await sql`SELECT * FROM user WHERE slug = ${slug}`
const userData = rows[0]
const currentUser = await getCurrentUser()
// 只返回与此查询相关的数据,而不是全部数据
// <https://www.w3.org/2001/tag/doc/APIMinimization>
return {
username: canSeeUsername(currentUser) ? userData.username : null,
phonenumber: canSeePhoneNumber(currentUser, userData.team)
? userData.phonenumber
: null,
}
}import { getProfileDTO } from '../../data/user-dto'
export default async function Page({ params }) {
const { slug } = await params
// 现在这个页面可以安全地传递此 profile,因为
// 它不应包含任何敏感信息。
const profile = await getProfileDTO(slug)
...
}小知识: 秘密密钥应存储在环境变量中,但只有数据访问层应访问
process.env。这可以防止秘密暴露给应用的其他部分。
组件级数据访问#
对于快速原型和迭代,可以直接在 Server Components 中放置数据库查询。
然而,这种方式更容易意外将私有数据暴露给客户端,例如:
import Profile from './components/profile.tsx'
export default async function Page({ params }) {
const { slug } = await params
const [rows] = await sql`SELECT * FROM user WHERE slug = ${slug}`
const userData = rows[0]
// 暴露:这会将 userData 中的所有字段暴露给客户端,因为
// 我们将数据从 Server Component 传递到了 Client。
return <Profile user={userData} />
}'use client'
// 错误:这是一个不好的 props 接口,因为它接受的数据
// 远超 Client Component 所需,并鼓励 server component
// 将所有这些数据向下传递。更好的方案是只接受一个包含
// 渲染 profile 所需字段的有限对象。
export default async function Profile({ user }: { user: User }) {
return (
<div>
<h1>{user.name}</h1>
...
</div>
)
}在将数据传递给 Client Component 之前,你应该对数据进行清理:
import { sql } from './db'
export async function getUser(slug: string) {
const [rows] = await sql`SELECT * FROM user WHERE slug = ${slug}`
const user = rows[0]
// 只返回公共字段
return {
name: user.name,
}
}import { getUser } from '../data/user'
import Profile from './ui/profile'
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
const publicProfile = await getUser(slug)
return <Profile user={publicProfile} />
}读取数据#
从服务器向客户端传递数据#
在初次加载时,Server 和 Client Components 都会在服务器上运行以生成 HTML。但是,它们在隔离的模块系统中执行。这确保 Server Components 可以访问私有数据和 API,而 Client Components 则不能。
Server Components:
- 仅在服务器上运行。
- 可以安全地访问环境变量、秘密、数据库和内部 API。
Client Components:
- 在预渲染期间在服务器上运行,但必须遵循与在浏览器中运行的代码相同的安全假设。
- 不得访问特权数据或仅限服务器的模块。
这确保应用默认安全,但仍可能通过数据获取或传递给组件的方式意外暴露私有数据。
污染标记(Tainting)#
为防止私有数据意外暴露给客户端,你可以使用 React 的 Taint API:
你可以通过 next.config.js 中的 experimental.taint 选项在 Next.js 应用中启用它:
module.exports = {
experimental: {
taint: true,
},
}这可以防止被标记污染的对象或值被传递给客户端。但是,这只是额外的保护层,你仍然应该在将数据传递到 React 的渲染上下文之前,在 DAL 中对数据进行过滤和清理。
小知识:
- 默认情况下,环境变量仅在 Server 上可用。Next.js 会将任何以
NEXT_PUBLIC_为前缀的环境变量暴露给客户端。了解更多。- 函数和类默认已被阻止传递给 Client Components。
防止仅限服务器的代码在客户端执行#
为防止仅限服务器的代码在客户端执行,你可以使用 server-only 包来标记模块:
import 'server-only'
//...如果在客户端环境中导入该模块,这会引发构建错误,从而确保专有代码或内部业务逻辑保留在服务器上。
Next.js 在内部处理 server-only 导入。不会使用来自 NPM 的这些包的内容。但是,如果你的 lint 规则标记了多余的依赖项,你可以安装它们以避免问题。
npm install server-onlyyarn add server-onlypnpm add server-onlybun add server-only在防止环境污染部分了解更多关于 server-only 的信息。
修改数据#
Next.js 使用 Server Actions 处理数据修改。
Server Actions 内置的安全特性#
默认情况下,当创建并导出 Server Action 时,它可通过直接的 POST 请求访问,而不仅仅是通过应用的 UI。这意味着,即使某个 Server Action 或工具函数没有在代码的其他地方被导入,它仍然可以从外部被调用。
为提高安全性,Next.js 具有以下内置特性:
- 安全的 action ID: Next.js 会创建加密的、非确定性的 ID,以允许客户端引用和调用 Server Action。这些 ID 会在各次构建之间定期重新计算,以增强安全性。
- 消除无用代码: 未使用的 Server Actions(通过其 ID 引用)会从客户端 bundle 中移除,以避免被公开访问。
小知识:
这些 ID 在编译期间创建,最多缓存 14 天。当启动新构建或构建缓存失效时,它们会重新生成。 这项安全改进降低了缺少身份验证层时的风险。但是,你仍应将 Server Actions 视为可通过直接 POST 请求访问,并在每个 Server Action 内部验证身份验证和授权。
// app/actions.js
'use server'
// 如果此 action **在**我们的应用中使用,Next.js
// 将创建一个安全的 ID,以允许客户端引用
// 并调用该 Server Action。
export async function updateUserAction(formData) {}
// 如果此 action **未**在我们的应用中使用,Next.js
// 将在 `next build` 期间自动移除这段代码,
// 并且不会创建公共端点。
export async function deleteUserAction(formData) {}验证客户端输入#
你应始终验证来自客户端的输入,因为它们很容易被修改。例如表单数据、URL 参数、标头和 searchParams:
// 错误:直接信任 searchParams
export default async function Page({ searchParams }) {
const isAdmin = (await searchParams).isAdmin
if (isAdmin === 'true') {
// 有漏洞:依赖不可信的客户端数据
return <AdminPanel />
}
}
// 正确:每次都重新验证
import { cookies } from 'next/headers'
import { verifyAdmin } from './auth'
export default async function Page() {
const cookieStore = await cookies()
const token = cookieStore.get('AUTH_TOKEN')
const isAdmin = await verifyAdmin(token)
if (isAdmin) {
return <AdminPanel />
}
}身份验证与授权#
页面级的身份验证检查不会延伸到其中定义的 Server Actions。务必在 action 内部重新验证:
import { auth } from '@/lib/auth'
import { redirect } from 'next/navigation'
export default async function AdminPage() {
const session = await auth()
if (!session?.user?.isAdmin) {
redirect('/login')
}
return (
<form
action={async () => {
'use server'
const session = await auth()
if (!session?.user?.isAdmin) {
throw new Error('Unauthorized')
}
await db.record.deleteMany()
}}
>
<button>Delete Records</button>
</form>
)
}action 中高亮的 auth() 检查至关重要。第 6 行的页面级 redirect 控制渲染哪个 UI,但 Server Action 是一个独立的入口点,必须自行验证调用方。
除了身份验证(用户是否已登录?),还要记得检查授权(该用户是否有权限对此特定资源执行操作?)。这可以防止不安全的直接对象引用(Insecure Direct Object Reference,IDOR)漏洞:
'use server'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db'
export async function deletePost(postId: string) {
const session = await auth()
if (!session?.user) {
throw new Error('Unauthorized')
}
const post = await db.post.findUnique({ where: { id: postId } })
// 检查用户是否拥有此资源
if (post.authorId !== session.user.id) {
throw new Error('Forbidden')
}
await db.post.delete({ where: { id: postId } })
}了解更多关于 Next.js 中身份验证的信息。
使用数据访问层处理数据修改#
正如我们推荐使用数据访问层来读取数据一样,你也可以将相同的模式应用于数据修改。这将身份验证、授权和数据库逻辑保留在专用的 server-only 模块中,而 "use server" action 保持精简。
import 'server-only'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db'
export async function deletePost(postId: string) {
const session = await auth()
if (!session?.user) {
throw new Error('Unauthorized')
}
const post = await db.post.findUnique({ where: { id: postId } })
if (post.authorId !== session.user.id) {
throw new Error('Forbidden')
}
await db.post.delete({ where: { id: postId } })
}然后,"use server" action 委托给 DAL:
'use server'
import { deletePost } from '@/data/posts'
import { revalidatePath } from 'next/cache'
export async function deletePostAction(postId: string) {
await deletePost(postId) // 身份验证 + 授权在 DAL 内部进行
revalidatePath('/posts')
}小知识: 你可以在数据访问层和
"use server"文件本身中都使用import 'server-only'。当 action 被导入到 Client Component 时(例如,将其传递给useActionState),两者都有效,因为"use server"模块是在仅限服务器的 webpack 层中解析的。
控制返回值#
Server Action 的返回值会被序列化并发送到客户端。只返回 UI 所需的内容,而不是原始数据库记录。
'use server'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db'
// 错误:返回完整的数据库记录,其中可能包含
// 客户端不应看到的内部字段。
export async function updateUser(data: FormData) {
const session = await auth()
if (!session?.user) {
throw new Error('Unauthorized')
}
return db.user.update({
where: { id: session.user.id },
data: { name: data.get('name') as string },
})
}
// 正确:只返回客户端所需的内容。
export async function updateUserSafe(data: FormData) {
const session = await auth()
if (!session?.user) {
throw new Error('Unauthorized')
}
await db.user.update({
where: { id: session.user.id },
data: { name: data.get('name') as string },
})
return { success: true }
}速率限制#
对于开销较大的操作(发送电子邮件、写入数据库),考虑添加速率限制以防止滥用。请参阅 Backend for Frontend 指南中的速率限制示例。
闭包与加密#
在组件内部定义 Server Action 会创建一个闭包,action 可以访问外部函数的作用域。例如,publish action 可以访问 publishVersion 变量:
export default async function Page() {
const publishVersion = await getLatestVersion();
async function publish() {
"use server";
if (publishVersion !== await getLatestVersion()) {
throw new Error('The version has changed since pressing publish');
}
...
}
return (
<form>
<button formAction={publish}>Publish</button>
</form>
);
}export default async function Page() {
const publishVersion = await getLatestVersion();
async function publish() {
"use server";
if (publishVersion !== await getLatestVersion()) {
throw new Error('The version has changed since pressing publish');
}
...
}
return (
<form>
<button formAction={publish}>Publish</button>
</form>
);
}当你需要在渲染时捕获数据的快照(例如 publishVersion),以便稍后在调用 action 时使用它时,闭包非常有用。
但是,为了实现这一点,捕获的变量会被发送到客户端,并在调用 action 时返回服务器。为防止敏感数据暴露给客户端,Next.js 会自动加密闭包中的变量。每次构建 Next.js 应用时,都会为每个 action 生成一个新的私钥。这意味着 action 只能针对特定的构建被调用。
小知识: 我们不建议仅依赖加密来防止敏感值暴露在客户端。
覆盖加密密钥(高级)#
当跨多台服务器自托管 Next.js 应用时,每个服务器实例最终可能使用不同的加密密钥,从而导致潜在的不一致。
为缓解此问题,你可以使用 process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY 环境变量来覆盖加密密钥。指定此变量可确保你的加密密钥在各次构建之间保持持久,并且所有服务器实例使用相同的密钥。
该密钥必须是 base64 编码的值,其解码后的长度与有效的 AES 密钥大小(16、24 或 32 字节)相匹配。Next.js 默认生成 32 字节的密钥。你可以使用平台的加密工具生成兼容的密钥,例如:
openssl rand -base64 32这是一个高级用例,在这种用例中,跨多个部署保持一致的加密行为对你的应用至关重要。请遵循标准的安全实践,如密钥轮换和签名。有关特定于部署的注意事项,请参阅自托管指南。
允许的来源(高级)#
由于 Server Actions 可以在 <form> 元素中调用,这使它们容易受到 CSRF 攻击。
在幕后,Server Actions 使用 POST 方法,并且只允许这种 HTTP 方法调用它们。这可以防止现代浏览器中的大多数 CSRF 漏洞,尤其是在默认使用 SameSite cookie 的情况下。
作为额外的保护,Next.js 中的 Server Actions 还会将 Origin 标头与 Host 标头(或 X-Forwarded-Host)进行比较。如果两者不匹配,请求将被中止。换句话说,Server Actions 只能在承载它的页面所在的同一主机上调用。
对于使用反向代理或多层后端架构(服务器 API 与生产域名不同)的大型应用,建议使用 experimental.serverActions.allowedOrigins 选项来指定额外的受信任主机。该选项接受一个字符串数组。
/** @type {import('next').NextConfig} */
module.exports = {
experimental: {
serverActions: {
allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
},
},
}了解更多关于安全与 Server Actions的信息。
避免在渲染期间产生副作用#
数据修改(例如让用户退出登录、更新数据库、使缓存失效)绝不应作为副作用出现,无论是在 Server 还是 Client Components 中。Next.js 明确禁止在渲染方法中设置 cookie 或触发缓存重新验证,以避免意外的副作用。
// 错误:在渲染期间触发数据修改
export default async function Page({ searchParams }) {
if ((await searchParams).logout) {
const cookieStore = await cookies()
cookieStore.delete('AUTH_TOKEN')
}
return <UserProfile />
}相反,你应该使用 Server Actions 来处理数据修改。
// 正确:使用 Server Actions 处理数据修改
import { logout } from './actions'
export default function Page() {
return (
<>
<UserProfile />
<form action={logout}>
<button type="submit">Logout</button>
</form>
</>
)
}小知识: Next.js 使用
POST请求来处理数据修改。这可以防止来自 GET 请求的意外副作用,降低跨站请求伪造(CSRF)风险。
审计#
如果你正在对 Next.js 项目进行审计,以下是一些我们建议重点关注的事项:
- 数据访问层: 是否已经确立了隔离的数据访问层的实践?验证数据库包和环境变量没有在数据访问层之外被导入。
"use client"文件: 组件的 props 是否期望私有数据?类型签名是否过于宽泛?"use server"文件: Action 的参数是在 action 中还是在数据访问层内部验证的?是否在 action 内部重新验证了用户?action 是否检查了资源的所有权(授权,而不仅仅是身份验证)?返回值是否过滤为仅包含客户端所需的内容?数据库访问是否委托给了server-only的数据访问层?/[param]/.带方括号的文件夹是用户输入。参数是否经过验证?proxy.ts和route.ts: 拥有很大的权限。花额外的时间使用传统技术对这些进行审计。定期或按照团队软件开发生命周期执行渗透测试或漏洞扫描。