NNext.js 中文网 GitHub

如何理解 Next.js 中的数据安全

了解 Next.js 内置的数据安全特性,以及保护应用数据的最佳实践。

React Server Components 提升了性能并简化了数据获取,但也改变了数据访问的位置和方式,改变了前端应用中处理数据的一些传统安全假设。

本指南将帮助你理解如何看待 Next.js 中的数据安全,以及如何实施最佳实践。

数据获取方式#

根据项目的规模和存在时间,我们推荐在 Next.js 中获取数据的主要方式有三种:

我们建议选择一种数据获取方式,避免混用。这让在你的代码库中工作的开发人员和安全审计人员都能清楚预期。

外部 HTTP API#

在现有项目中采用 Server Components 时,你应遵循零信任模型。你可以继续使用 fetch 从 Server Components 调用现有的 API 端点(如 REST 或 GraphQL),就像在 Client Components 中一样。

app/page.tsx
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)。

这种方式集中管理所有数据访问逻辑,使执行一致的数据访问变得更容易,并降低授权漏洞的风险。你还可以受益于在请求的不同部分之间共享内存缓存。

data/auth.ts
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)
})
data/user-dto.tsx
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,
  }
}
app/page.tsx
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 中放置数据库查询。

然而,这种方式更容易意外将私有数据暴露给客户端,例如:

app/page.tsx
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} />
}
app/ui/profile.tsx
'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 之前,你应该对数据进行清理:

data/user.ts
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,
  }
}
app/page.tsx
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 应用中启用它:

next.config.js
module.exports = {
  experimental: {
    taint: true,
  },
}

这可以防止被标记污染的对象或值被传递给客户端。但是,这只是额外的保护层,你仍然应该在将数据传递到 React 的渲染上下文之前,在 DAL 中对数据进行过滤和清理。

小知识:

  • 默认情况下,环境变量仅在 Server 上可用。Next.js 会将任何以 NEXT_PUBLIC_ 为前缀的环境变量暴露给客户端。了解更多。
  • 函数和类默认已被阻止传递给 Client Components。

防止仅限服务器的代码在客户端执行#

为防止仅限服务器的代码在客户端执行,你可以使用 server-only 包来标记模块:

lib/data.ts
import 'server-only'

//...

如果在客户端环境中导入该模块,这会引发构建错误,从而确保专有代码或内部业务逻辑保留在服务器上。

Next.js 在内部处理 server-only 导入。不会使用来自 NPM 的这些包的内容。但是,如果你的 lint 规则标记了多余的依赖项,你可以安装它们以避免问题。

bash · npm
npm install server-only
bash · yarn
yarn add server-only
bash · pnpm
pnpm add server-only
bash · bun
bun 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 内部验证身份验证和授权。

jsx
// 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:

app/page.tsx
// 错误:直接信任 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 内部重新验证:

app/admin/page.tsx
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)漏洞:

app/actions.ts
'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 保持精简。

data/posts.ts
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:

app/actions.ts
'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 所需的内容,而不是原始数据库记录。

app/actions.ts
'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 变量:

app/page.tsx
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>
  );
}
app/page.js
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 字节的密钥。你可以使用平台的加密工具生成兼容的密钥,例如:

bash
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 选项来指定额外的受信任主机。该选项接受一个字符串数组。

next.config.js
/** @type {import('next').NextConfig} */
module.exports = {
  experimental: {
    serverActions: {
      allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
    },
  },
}

了解更多关于安全与 Server Actions的信息。

避免在渲染期间产生副作用#

数据修改(例如让用户退出登录、更新数据库、使缓存失效)绝不应作为副作用出现,无论是在 Server 还是 Client Components 中。Next.js 明确禁止在渲染方法中设置 cookie 或触发缓存重新验证,以避免意外的副作用。

app/page.tsx
// 错误:在渲染期间触发数据修改
export default async function Page({ searchParams }) {
  if ((await searchParams).logout) {
    const cookieStore = await cookies()
    cookieStore.delete('AUTH_TOKEN')
  }

  return <UserProfile />
}

相反,你应该使用 Server Actions 来处理数据修改。

app/page.tsx
// 正确:使用 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: 拥有很大的权限。花额外的时间使用传统技术对这些进行审计。定期或按照团队软件开发生命周期执行渗透测试或漏洞扫描。
Next.js 中文网