NNext.js 中文网 GitHub

taint

experimental

启用对象和值的污染标记(taint)。

用法#

taint 选项支持使用实验性的 React API 来标记对象和值。此功能有助于防止敏感数据被意外传递到客户端。启用后,你可以使用:

小知识:激活此标志还会为 app 目录启用 React 的 experimental 渠道,并标记 process.env,使其无法作为一个整体传递给 Client Component。

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    taint: true,
  },
}

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    taint: true,
  },
}

module.exports = nextConfig

警告: 请勿将 taint API 作为防止敏感数据暴露给客户端的唯一机制。请参阅我们的安全建议。

taint API 使你能够采取防御性措施,通过声明式地显式标记不允许通过 Server-Client 边界的数据。当某个对象或值通过 Server-Client 边界传递时,React 会抛出错误。

这在以下情况下很有帮助:

  • 读取数据的方法不受你控制
  • 你必须处理并非由你定义的敏感数据结构
  • 在 Server Component 渲染期间访问了敏感数据

建议对你的数据和 API 进行建模,使敏感数据不会返回到不需要它的上下文中。

注意事项#

  • 污染标记只能通过引用跟踪对象。复制对象会创建一个未标记的版本,该版本会失去 API 提供的所有保证。你需要对该副本进行标记。
  • 内置的 process.env 标记仅作用于对象引用。读取单个变量(例如 process.env.MY_VAR)并将结果字符串传递给 Client Component 不受影响,传递像 { ...process.env } 这样的副本也不受影响。
  • 污染标记无法跟踪从已标记值派生的数据。你还需要对派生值进行标记。
  • 只要值的生命周期引用仍在作用域内,值就会保持被标记状态。有关更多信息,请参阅 experimental_taintUniqueValue 参数参考。

示例#

标记对象引用#

在此示例中,getUserDetails 函数返回有关给定用户的数据。我们标记用户对象的引用,使其无法跨越 Server-Client 边界。例如,假设 UserCard 是一个 Client Component。

ts
import { experimental_taintObjectReference } from 'react'

async function getUserDetails(id: string): Promise<UserDetails> {
  const user = await db.queryUserById(id)

  experimental_taintObjectReference(
    'Do not use the entire user info object. Instead, select only the fields you need.',
    user
  )

  return user
}
js
import { experimental_taintObjectReference } from 'react'

async function getUserDetails(id) {
  const user = await db.queryUserById(id)

  experimental_taintObjectReference(
    'Do not use the entire user info object. Instead, select only the fields you need.',
    user
  )

  return user
}

我们仍然可以访问被标记的 userDetails 对象中的单个字段。

tsx
export async function ContactPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const userDetails = await getUserDetails(id)

  return (
    <UserCard
      firstName={userDetails.firstName}
      lastName={userDetails.lastName}
    />
  )
}
jsx
export async function ContactPage({ params }) {
  const { id } = await params
  const userDetails = await getUserDetails(id)

  return (
    <UserCard
      firstName={userDetails.firstName}
      lastName={userDetails.lastName}
    />
  )
}

现在,将整个对象传递给 Client Component 将抛出错误。

tsx
export async function ContactPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const userDetails = await getUserDetails(id)

  // 抛出错误
  return <UserCard user={userDetails} />
}
jsx
export async function ContactPage({ params }) {
  const { id } = await params
  const userDetails = await getUserDetails(id)

  // 抛出错误
  return <UserCard user={userDetails} />
}

标记唯一值#

在此示例中,我们可以通过 await 调用 configService.getConfigDetails 来访问服务器配置。但是,系统配置包含我们不想暴露给客户端的 SERVICE_API_KEY。

我们可以标记 config.SERVICE_API_KEY 值。

ts
import { experimental_taintUniqueValue } from 'react'

async function getSystemConfig(): Promise<SystemConfig> {
  const config = await configService.getConfigDetails()

  experimental_taintUniqueValue(
    'Do not pass configuration tokens to the client',
    config,
    config.SERVICE_API_KEY
  )

  return config
}
js
import { experimental_taintUniqueValue } from 'react'

async function getSystemConfig() {
  const config = await configService.getConfigDetails()

  experimental_taintUniqueValue(
    'Do not pass configuration tokens to the client',
    config,
    config.SERVICE_API_KEY
  )

  return config
}

我们仍然可以访问 systemConfig 对象的其他属性。

tsx
export async function Dashboard() {
  const systemConfig = await getSystemConfig()

  return <ClientDashboard version={systemConfig.SERVICE_API_VERSION} />
}

但是,将 SERVICE_API_KEY 传递给 ClientDashboard 会抛出错误。

tsx
export async function Dashboard() {
  const systemConfig = await getSystemConfig()
  // 有人在 PR 中犯了错误
  const version = systemConfig.SERVICE_API_KEY

  return <ClientDashboard version={version} />
}

请注意,即使 systemConfig.SERVICE_API_KEY 被重新赋值给一个新变量,将其传递给 Client Component 仍然会抛出错误。

而从未标记的唯一值派生出的值则会被暴露给客户端。

tsx
export async function Dashboard() {
  const systemConfig = await getSystemConfig()
  // 有人在 PR 中犯了错误
  const version = `version::${systemConfig.SERVICE_API_KEY}`

  return <ClientDashboard version={version} />
}

更好的做法是从 getSystemConfig 返回的数据中移除 SERVICE_API_KEY。

Next.js 中文网