taint

此功能目前处于实验阶段，可能会有所更改，不建议用于生产环境。欢迎试用并在 GitHub 上分享您的反馈。

用法

taint 选项启用了对实验性 React API 的支持，用于污染对象和值。此功能有助于防止敏感数据意外传递给客户端。启用后，您可以使用

experimental_taintObjectReference 污染对象引用。
experimental_taintUniqueValue 污染唯一值。

须知：激活此标志还会在 app 目录中启用 React experimental 频道。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    taint: true,
  },
}
 
export default nextConfig

警告： 不要仅仅依靠 taint API 来防止敏感数据暴露给客户端。请参阅我们的安全建议。

Taint API 允许您通过声明性地、明确地标记不允许通过服务器-客户端边界的数据来进行防御。当对象或值通过服务器-客户端边界时，React 会抛出错误。

这在以下情况下很有用：

读取数据的方法不在您的控制之下
您必须处理非您定义的敏感数据形状
在服务器组件渲染期间访问敏感数据

建议对您的数据和 API 进行建模，以便敏感数据不会返回到不需要它的上下文中。

注意事项

污染只能通过引用跟踪对象。复制对象会创建一个未污染的版本，这将失去 API 提供的所有保证。您需要污染副本。
污染无法跟踪从污染值派生出的数据。您还需要污染派生值。
值的污染在它们的生命周期引用在范围内时一直有效。有关更多信息，请参阅 experimental_taintUniqueValue 参数参考。

示例

污染对象引用

在这种情况下，getUserDetails 函数返回给定用户的数据。我们污染用户对象引用，使其无法跨越服务器-客户端边界。例如，假设 UserCard 是一个客户端组件。

import { experimental_taintObjectReference } from 'react'
 
function getUserDetails(id: string): 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
}

我们仍然可以从被污染的 userDetails 对象中访问单个字段。

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}
    />
  )
}

现在，将整个对象传递给客户端组件将抛出错误。

export async function ContactPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const userDetails = await getUserDetails(id)
 
  // Throws an error
  return <UserCard user={userDetails} />
}

污染唯一值

在这种情况下，我们可以通过等待对 config.getConfigDetails 的调用来访问服务器配置。但是，系统配置包含我们不想暴露给客户端的 SERVICE_API_KEY。

我们可以污染 config.SERVICE_API_KEY 值。

import { experimental_taintUniqueValue } from 'react'
 
function getSystemConfig(): SystemConfig {
  const config = await config.getConfigDetails()
 
  experimental_taintUniqueValue(
    'Do not pass configuration tokens to the client',
    config,
    config.SERVICE_API_KEY
  )
 
  return config
}

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

export async function Dashboard() {
  const systemConfig = await getSystemConfig()
 
  return <ClientDashboard version={systemConfig.SERVICE_API_VERSION} />
}

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

export async function Dashboard() {
  const systemConfig = await getSystemConfig()
  // Someone makes a mistake in a PR
  const version = systemConfig.SERVICE_API_KEY
 
  return <ClientDashboard version={version} />
}

请注意，即使 systemConfig.SERVICE_API_KEY 被重新分配给新变量。将其传递给客户端组件仍然会抛出错误。

然而，从受污染的唯一值派生的值将被暴露给客户端。

export async function Dashboard() {
  const systemConfig = await getSystemConfig()
  // Someone makes a mistake in a PR
  const version = `version::${systemConfig.SERVICE_API_KEY}`
 
  return <ClientDashboard version={version} />
}

更好的方法是从 getSystemConfig 返回的数据中删除 SERVICE_API_KEY。