如何为您的 Next.js 应用程序设置内容安全策略 (CSP)

Content Security Policy (CSP) 对于保护您的 Next.js 应用程序免受各种安全威胁（例如跨站脚本 (XSS)、点击劫持和其他代码注入攻击）至关重要。

通过使用 CSP，开发者可以指定哪些来源允许用于内容源、脚本、样式表、图像、字体、对象、媒体（音频、视频）、iframe 等。

示例

Strict CSP

一次性随机数 (Nonces)

一次性随机数（nonce）是一种为单次使用而创建的独特随机字符串。它与 CSP 结合使用，以选择性地允许某些内联脚本或样式执行，从而绕过严格的 CSP 指令。

为什么要使用一次性随机数？

CSP 可以阻止内联和外部脚本以防止攻击。一次性随机数允许您安全地运行特定脚本——仅当它们包含匹配的 nonce值时。

如果攻击者想将脚本加载到您的页面中，他们就需要猜测该 nonce值。这就是为什么 nonce值必须对每个请求都是不可预测且唯一的。

使用 Proxy 添加一次性随机数

Proxy 允许您在页面渲染之前添加请求头并生成一次性随机数。

每次页面被查看时，都应该生成一个新的一次性随机数。这意味着您必须使用动态渲染来添加一次性随机数。

例如：

typescript

import { NextRequest, NextResponse } from 'next/server'

export function proxy(request: NextRequest) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const cspHeader = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic';
    style-src 'self' 'nonce-${nonce}';
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`
  // Replace newline characters and spaces
  const contentSecurityPolicyHeaderValue = cspHeader
    .replace(/\s{2,}/g, ' ')
    .trim()

  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-nonce', nonce)

  requestHeaders.set(
    'Content-Security-Policy',
    contentSecurityPolicyHeaderValue
  )

  const response = NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  })
  response.headers.set(
    'Content-Security-Policy',
    contentSecurityPolicyHeaderValue
  )

  return response
}

javascript

import { NextResponse } from 'next/server'

export function proxy(request) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const cspHeader = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic';
    style-src 'self' 'nonce-${nonce}';
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`
  // Replace newline characters and spaces
  const contentSecurityPolicyHeaderValue = cspHeader
    .replace(/\s{2,}/g, ' ')
    .trim()

  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-nonce', nonce)
  requestHeaders.set(
    'Content-Security-Policy',
    contentSecurityPolicyHeaderValue
  )

  const response = NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  })
  response.headers.set(
    'Content-Security-Policy',
    contentSecurityPolicyHeaderValue
  )

  return response
}

默认情况下，Proxy 会对所有请求运行。您可以使用 matcher 过滤 Proxy 以使其在特定路径上运行。

我们建议忽略匹配的预取（来自 next/link）和不需要 CSP 请求头的静态资源。

typescript

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     */
    {
      source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
  ],
}

javascript

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     */
    {
      source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
  ],
}

一次性随机数在 Next.js 中的工作原理

要使用一次性随机数，您的页面必须是动态渲染的。这是因为 Next.js 在服务器端渲染期间根据请求中存在的 CSP 请求头应用一次性随机数。静态页面在构建时生成，此时不存在请求或响应头——因此无法注入一次性随机数。

以下是动态渲染页面中一次性随机数支持的工作原理：

Proxy 生成一次性随机数：您的 proxy 为请求创建一个唯一的一次性随机数，将其添加到您的 Content-Security-Policy 请求头中，并将其设置在自定义的 x-nonce 请求头中。
Next.js 提取一次性随机数：在渲染期间，Next.js 解析 Content-Security-Policy 请求头，并使用 'nonce-{value}' 模式提取一次性随机数。
一次性随机数自动应用：Next.js 将一次性随机数附加到：
- 框架脚本（React、Next.js 运行时）
- 页面特定的 JavaScript 包
- Next.js 生成的内联样式和脚本
- 任何使用 nonce prop 的 <Script> 组件

由于这种自动行为，您无需手动为每个标签添加一次性随机数。

强制动态渲染

如果您正在使用一次性随机数，您可能需要显式地选择页面进行动态渲染：

tsx

import { connection } from 'next/server'

export default async function Page() {
  // wait for an incoming request to render this page
  await connection()
  // Your page content
}

jsx

import { connection } from 'next/server'

export default async function Page() {
  // wait for an incoming request to render this page
  await connection()
  // Your page content
}

读取一次性随机数

Pages Router Only

您可以使用 getServerSideProps 为您的页面提供一次性随机数：

tsx

import Script from 'next/script'

import type { GetServerSideProps } from 'next'

export default function Page({ nonce }) {
  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

export const getServerSideProps: GetServerSideProps = async ({ req }) => {
  const nonce = req.headers['x-nonce']
  return { props: { nonce } }
}

jsx

import Script from 'next/script'
export default function Page({ nonce }) {
  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

export async function getServerSideProps({ req }) {
  const nonce = req.headers['x-nonce']
  return { props: { nonce } }
}

您还可以在 Pages Router 应用程序的 _document.tsx 中访问一次性随机数：

tsx

import Document, {
  Html,
  Head,
  Main,
  NextScript,
  DocumentContext,
  DocumentInitialProps,
} from 'next/document'

interface ExtendedDocumentProps extends DocumentInitialProps {
  nonce?: string
}

class MyDocument extends Document<ExtendedDocumentProps> {
  static async getInitialProps(
    ctx: DocumentContext
  ): Promise<ExtendedDocumentProps> {
    const initialProps = await Document.getInitialProps(ctx)
    const nonce = ctx.req?.headers?.['x-nonce'] as string | undefined

    return {
      ...initialProps,
      nonce,
    }
  }

  render() {
    const { nonce } = this.props

    return (
      <Html lang="en">
        <Head nonce={nonce} />
        <body>
          <Main />
          <NextScript nonce={nonce} />
        </body>
      </Html>
    )
  }
}

export default MyDocument

jsx

import Document, { Html, Head, Main, NextScript } from 'next/document'

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx)
    const nonce = ctx.req?.headers?.['x-nonce']

    return {
      ...initialProps,
      nonce,
    }
  }

  render() {
    const { nonce } = this.props

    return (
      <Html lang="en">
        <Head nonce={nonce} />
        <body>
          <Main />
          <NextScript nonce={nonce} />
        </body>
      </Html>
    )
  }
}

export default MyDocument

App Router Only

您可以使用 headers 从服务器组件中读取一次性随机数：

tsx

import { headers } from 'next/headers'
import Script from 'next/script'

export default async function Page() {
  const nonce = (await headers()).get('x-nonce')

  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

jsx

import { headers } from 'next/headers'
import Script from 'next/script'

export default async function Page() {
  const nonce = (await headers()).get('x-nonce')

  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

静态渲染与动态渲染与 CSP

使用一次性随机数对您的 Next.js 应用程序的渲染方式具有重要影响：

动态渲染要求

当您在 CSP 中使用一次性随机数时，所有页面都必须动态渲染。这意味着：

页面将成功构建，但如果未正确配置动态渲染，可能会遇到运行时错误
每个请求都会生成一个带有新一次性随机数的全新页面
静态优化和增量静态再生 (ISR) 被禁用
页面无法在没有额外配置的情况下被 CDN 缓存
部分预渲染 (PPR) 与基于一次性随机数的 CSP 不兼容，因为静态 shell 脚本无法访问一次性随机数

性能影响

从静态渲染转向动态渲染会影响性能：

初始页面加载速度较慢：页面必须在每个请求上生成
服务器负载增加：每个请求都需要服务器端渲染
无 CDN 缓存：动态页面默认无法在边缘缓存
更高的托管成本：动态渲染需要更多的服务器资源

何时使用一次性随机数

在以下情况下考虑使用一次性随机数：

您有禁止 'unsafe-inline' 的严格安全要求
您的应用程序处理敏感数据
您需要允许特定的内联脚本同时阻止其他脚本
合规性要求强制执行严格的 CSP

不使用一次性随机数

对于不需要一次性随机数的应用程序，您可以直接在 next.config.js 文件中设置 CSP 请求头：

javascript

const cspHeader = `
    default-src 'self';
    script-src 'self' 'unsafe-eval' 'unsafe-inline';
    style-src 'self' 'unsafe-inline';
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`

module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: cspHeader.replace(/\n/g, ''),
          },
        ],
      },
    ]
  },
}

App Router Only

子资源完整性（实验性）

作为一次性随机数的替代方案，Next.js 提供了使用子资源完整性 (SRI) 的基于哈希的 CSP 实验性支持。这种方法允许您在保持严格 CSP 的同时维护静态生成。

提示：此功能是实验性的，仅在 App Router 应用程序中使用 webpack 打包器时可用。

SRI 工作原理

SRI 不使用一次性随机数，而是在构建时生成 JavaScript 文件的加密哈希。这些哈希被作为 integrity 属性添加到 script 标签中，允许浏览器验证文件在传输过程中是否被修改。

启用 SRI

将实验性的 SRI 配置添加到您的 next.config.js 中：

javascript

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    sri: {
      algorithm: 'sha256', // or 'sha384' or 'sha512'
    },
  },
}

module.exports = nextConfig

CSP 与 SRI 配置

启用 SRI 后，您可以继续使用现有的 CSP 策略。SRI 通过向您的资产添加 integrity 属性来独立工作：

提示：对于动态渲染场景，如果需要，您仍然可以使用 proxy 生成一次性随机数，结合 SRI integrity 属性和基于一次性随机数的 CSP 方法。

javascript

const cspHeader = `
    default-src 'self';
    script-src 'self';
    style-src 'self';
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`

module.exports = {
  experimental: {
    sri: {
      algorithm: 'sha256',
    },
  },
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: cspHeader.replace(/\n/g, ''),
          },
        ],
      },
    ]
  },
}

SRI 相对于一次性随机数的优势

静态生成：页面可以静态生成和缓存
CDN 兼容性：静态页面与 CDN 缓存协同工作
更好的性能：每个请求不需要服务器端渲染
构建时安全性：哈希在构建时生成，确保完整性

SRI 的局限性

实验性：功能可能会更改或移除
仅限 Webpack：不适用于 Turbopack
仅限 App Router：在 Pages Router 中不支持
仅限构建时：无法处理动态生成的脚本

开发与生产环境考虑

CSP 的实现在开发和生产环境之间存在差异：

开发环境

在开发环境中，您需要启用 'unsafe-eval' 来支持提供额外调试信息的 API：

typescript

export function proxy(request: NextRequest) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const isDev = process.env.NODE_ENV === 'development'

  const cspHeader = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic' ${isDev ? "'unsafe-eval'" : ''};
    style-src 'self' ${isDev ? "'unsafe-inline'" : `'nonce-${nonce}'`};
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`

  // Rest of proxy implementation
}

javascript

export function proxy(request) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const isDev = process.env.NODE_ENV === 'development'

  const cspHeader = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic' ${isDev ? "'unsafe-eval'" : ''};
    style-src 'self' ${isDev ? "'unsafe-inline'" : `'nonce-${nonce}'`};
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`

  // Rest of proxy implementation
}

生产部署

生产环境中的常见问题：

未应用一次性随机数：确保您的 proxy 在所有必要的路由上运行
静态资源被阻止：验证您的 CSP 允许 Next.js 静态资源
第三方脚本：将必要的域添加到您的 CSP 策略中

故障排除

第三方脚本

App Router Only

当将第三方脚本与 CSP 一起使用时：

tsx

import { GoogleTagManager } from '@next/third-parties/google'
import { headers } from 'next/headers'

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const nonce = (await headers()).get('x-nonce')

  return (
    <html lang="en">
      <body>
        {children}
        <GoogleTagManager gtmId="GTM-XYZ" nonce={nonce} />
      </body>
    </html>
  )
}

jsx

import { GoogleTagManager } from '@next/third-parties/google'
import { headers } from 'next/headers'

export default async function RootLayout({ children }) {
  const nonce = (await headers()).get('x-nonce')

  return (
    <html lang="en">
      <body>
        {children}
        <GoogleTagManager gtmId="GTM-XYZ" nonce={nonce} />
      </body>
    </html>
  )
}

Pages Router Only

当将第三方脚本与 CSP 一起使用时，请确保您添加了必要的域并传递了一次性随机数：

tsx

import type { AppProps } from 'next/app'
import Script from 'next/script'

export default function App({ Component, pageProps }: AppProps) {
  const nonce = pageProps.nonce

  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://www.googletagmanager.com/gtag/js"
        strategy="afterInteractive"
        nonce={nonce}
      />
    </>
  )
}

jsx

import Script from 'next/script'

export default function App({ Component, pageProps }) {
  const nonce = pageProps.nonce

  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://www.googletagmanager.com/gtag/js"
        strategy="afterInteractive"
        nonce={nonce}
      />
    </>
  )
}

更新您的 CSP 以允许第三方域：

typescript

const cspHeader = `
  default-src 'self';
  script-src 'self' 'nonce-${nonce}' 'strict-dynamic' https://www.googletagmanager.com;
  connect-src 'self' https://www.google-analytics.com;
  img-src 'self' data: https://www.google-analytics.com;
`

javascript

const cspHeader = `
  default-src 'self';
  script-src 'self' 'nonce-${nonce}' 'strict-dynamic' https://www.googletagmanager.com;
  connect-src 'self' https://www.google-analytics.com;
  img-src 'self' data: https://www.google-analytics.com;
`

常见 CSP 违规

内联样式：使用支持一次性随机数的 CSS-in-JS 库或将样式移动到外部文件
动态导入：确保您的 script-src 策略中允许动态导入
WebAssembly：如果使用 WebAssembly，请添加 'wasm-unsafe-eval'
Service Worker：为 Service Worker 脚本添加适当的策略

版本历史

版本	变更
`v14.0.0`	添加了基于哈希的 CSP 的实验性 SRI 支持
`v13.4.20`	推荐用于正确的一次性随机数处理和 CSP 请求头解析。

Content Security Policy (CSP) 对于保护您的 Next.js 应用程序免受各种安全威胁（例如跨站脚本 (XSS)、点击劫持和其他代码注入攻击）至关重要。

通过使用 CSP，开发者可以指定哪些来源允许用于内容源、脚本、样式表、图像、字体、对象、媒体（音频、视频）、iframe 等。

示例

Strict CSP

一次性随机数 (Nonces)

为什么要使用一次性随机数？

CSP 可以阻止内联和外部脚本以防止攻击。一次性随机数允许您安全地运行特定脚本——仅当它们包含匹配的 nonce值时。

如果攻击者想将脚本加载到您的页面中，他们就需要猜测该 nonce值。这就是为什么 nonce值必须对每个请求都是不可预测且唯一的。

使用 Proxy 添加一次性随机数

Proxy 允许您在页面渲染之前添加请求头并生成一次性随机数。

每次页面被查看时，都应该生成一个新的一次性随机数。这意味着您必须使用动态渲染来添加一次性随机数。

例如：

typescript

import { NextRequest, NextResponse } from 'next/server'

export function proxy(request: NextRequest) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const cspHeader = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic';
    style-src 'self' 'nonce-${nonce}';
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`
  // Replace newline characters and spaces
  const contentSecurityPolicyHeaderValue = cspHeader
    .replace(/\s{2,}/g, ' ')
    .trim()

  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-nonce', nonce)

  requestHeaders.set(
    'Content-Security-Policy',
    contentSecurityPolicyHeaderValue
  )

  const response = NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  })
  response.headers.set(
    'Content-Security-Policy',
    contentSecurityPolicyHeaderValue
  )

  return response
}

javascript

import { NextResponse } from 'next/server'

export function proxy(request) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const cspHeader = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic';
    style-src 'self' 'nonce-${nonce}';
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`
  // Replace newline characters and spaces
  const contentSecurityPolicyHeaderValue = cspHeader
    .replace(/\s{2,}/g, ' ')
    .trim()

  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-nonce', nonce)
  requestHeaders.set(
    'Content-Security-Policy',
    contentSecurityPolicyHeaderValue
  )

  const response = NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  })
  response.headers.set(
    'Content-Security-Policy',
    contentSecurityPolicyHeaderValue
  )

  return response
}

默认情况下，Proxy 会对所有请求运行。您可以使用 matcher 过滤 Proxy 以使其在特定路径上运行。

我们建议忽略匹配的预取（来自 next/link）和不需要 CSP 请求头的静态资源。

typescript

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     */
    {
      source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
  ],
}

javascript

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     */
    {
      source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
  ],
}

一次性随机数在 Next.js 中的工作原理

以下是动态渲染页面中一次性随机数支持的工作原理：

Proxy 生成一次性随机数：您的 proxy 为请求创建一个唯一的一次性随机数，将其添加到您的 Content-Security-Policy 请求头中，并将其设置在自定义的 x-nonce 请求头中。
Next.js 提取一次性随机数：在渲染期间，Next.js 解析 Content-Security-Policy 请求头，并使用 'nonce-{value}' 模式提取一次性随机数。
一次性随机数自动应用：Next.js 将一次性随机数附加到：
- 框架脚本（React、Next.js 运行时）
- 页面特定的 JavaScript 包
- Next.js 生成的内联样式和脚本
- 任何使用 nonce prop 的 <Script> 组件

由于这种自动行为，您无需手动为每个标签添加一次性随机数。

强制动态渲染

如果您正在使用一次性随机数，您可能需要显式地选择页面进行动态渲染：

tsx

import { connection } from 'next/server'

export default async function Page() {
  // wait for an incoming request to render this page
  await connection()
  // Your page content
}

jsx

import { connection } from 'next/server'

export default async function Page() {
  // wait for an incoming request to render this page
  await connection()
  // Your page content
}

读取一次性随机数

Pages Router Only

您可以使用 getServerSideProps 为您的页面提供一次性随机数：

tsx

import Script from 'next/script'

import type { GetServerSideProps } from 'next'

export default function Page({ nonce }) {
  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

export const getServerSideProps: GetServerSideProps = async ({ req }) => {
  const nonce = req.headers['x-nonce']
  return { props: { nonce } }
}

jsx

import Script from 'next/script'
export default function Page({ nonce }) {
  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

export async function getServerSideProps({ req }) {
  const nonce = req.headers['x-nonce']
  return { props: { nonce } }
}

您还可以在 Pages Router 应用程序的 _document.tsx 中访问一次性随机数：

tsx

import Document, {
  Html,
  Head,
  Main,
  NextScript,
  DocumentContext,
  DocumentInitialProps,
} from 'next/document'

interface ExtendedDocumentProps extends DocumentInitialProps {
  nonce?: string
}

class MyDocument extends Document<ExtendedDocumentProps> {
  static async getInitialProps(
    ctx: DocumentContext
  ): Promise<ExtendedDocumentProps> {
    const initialProps = await Document.getInitialProps(ctx)
    const nonce = ctx.req?.headers?.['x-nonce'] as string | undefined

    return {
      ...initialProps,
      nonce,
    }
  }

  render() {
    const { nonce } = this.props

    return (
      <Html lang="en">
        <Head nonce={nonce} />
        <body>
          <Main />
          <NextScript nonce={nonce} />
        </body>
      </Html>
    )
  }
}

export default MyDocument

jsx

import Document, { Html, Head, Main, NextScript } from 'next/document'

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx)
    const nonce = ctx.req?.headers?.['x-nonce']

    return {
      ...initialProps,
      nonce,
    }
  }

  render() {
    const { nonce } = this.props

    return (
      <Html lang="en">
        <Head nonce={nonce} />
        <body>
          <Main />
          <NextScript nonce={nonce} />
        </body>
      </Html>
    )
  }
}

export default MyDocument

App Router Only

您可以使用 headers 从服务器组件中读取一次性随机数：

tsx

import { headers } from 'next/headers'
import Script from 'next/script'

export default async function Page() {
  const nonce = (await headers()).get('x-nonce')

  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

jsx

import { headers } from 'next/headers'
import Script from 'next/script'

export default async function Page() {
  const nonce = (await headers()).get('x-nonce')

  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

静态渲染与动态渲染与 CSP

使用一次性随机数对您的 Next.js 应用程序的渲染方式具有重要影响：

动态渲染要求

当您在 CSP 中使用一次性随机数时，所有页面都必须动态渲染。这意味着：

页面将成功构建，但如果未正确配置动态渲染，可能会遇到运行时错误
每个请求都会生成一个带有新一次性随机数的全新页面
静态优化和增量静态再生 (ISR) 被禁用
页面无法在没有额外配置的情况下被 CDN 缓存
部分预渲染 (PPR) 与基于一次性随机数的 CSP 不兼容，因为静态 shell 脚本无法访问一次性随机数

性能影响

从静态渲染转向动态渲染会影响性能：

初始页面加载速度较慢：页面必须在每个请求上生成
服务器负载增加：每个请求都需要服务器端渲染
无 CDN 缓存：动态页面默认无法在边缘缓存
更高的托管成本：动态渲染需要更多的服务器资源

何时使用一次性随机数

在以下情况下考虑使用一次性随机数：

您有禁止 'unsafe-inline' 的严格安全要求
您的应用程序处理敏感数据
您需要允许特定的内联脚本同时阻止其他脚本
合规性要求强制执行严格的 CSP

不使用一次性随机数

对于不需要一次性随机数的应用程序，您可以直接在 next.config.js 文件中设置 CSP 请求头：

javascript

const cspHeader = `
    default-src 'self';
    script-src 'self' 'unsafe-eval' 'unsafe-inline';
    style-src 'self' 'unsafe-inline';
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`

module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: cspHeader.replace(/\n/g, ''),
          },
        ],
      },
    ]
  },
}

App Router Only

子资源完整性（实验性）

提示：此功能是实验性的，仅在 App Router 应用程序中使用 webpack 打包器时可用。

SRI 工作原理

启用 SRI

将实验性的 SRI 配置添加到您的 next.config.js 中：

javascript

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    sri: {
      algorithm: 'sha256', // or 'sha384' or 'sha512'
    },
  },
}

module.exports = nextConfig

CSP 与 SRI 配置

启用 SRI 后，您可以继续使用现有的 CSP 策略。SRI 通过向您的资产添加 integrity 属性来独立工作：

提示：对于动态渲染场景，如果需要，您仍然可以使用 proxy 生成一次性随机数，结合 SRI integrity 属性和基于一次性随机数的 CSP 方法。

javascript

const cspHeader = `
    default-src 'self';
    script-src 'self';
    style-src 'self';
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`

module.exports = {
  experimental: {
    sri: {
      algorithm: 'sha256',
    },
  },
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: cspHeader.replace(/\n/g, ''),
          },
        ],
      },
    ]
  },
}

SRI 相对于一次性随机数的优势

静态生成：页面可以静态生成和缓存
CDN 兼容性：静态页面与 CDN 缓存协同工作
更好的性能：每个请求不需要服务器端渲染
构建时安全性：哈希在构建时生成，确保完整性

SRI 的局限性

实验性：功能可能会更改或移除
仅限 Webpack：不适用于 Turbopack
仅限 App Router：在 Pages Router 中不支持
仅限构建时：无法处理动态生成的脚本

开发与生产环境考虑

CSP 的实现在开发和生产环境之间存在差异：

开发环境

在开发环境中，您需要启用 'unsafe-eval' 来支持提供额外调试信息的 API：

typescript

export function proxy(request: NextRequest) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const isDev = process.env.NODE_ENV === 'development'

  const cspHeader = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic' ${isDev ? "'unsafe-eval'" : ''};
    style-src 'self' ${isDev ? "'unsafe-inline'" : `'nonce-${nonce}'`};
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`

  // Rest of proxy implementation
}

javascript

export function proxy(request) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const isDev = process.env.NODE_ENV === 'development'

  const cspHeader = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic' ${isDev ? "'unsafe-eval'" : ''};
    style-src 'self' ${isDev ? "'unsafe-inline'" : `'nonce-${nonce}'`};
    img-src 'self' blob: data:;
    font-src 'self';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
    frame-ancestors 'none';
    upgrade-insecure-requests;
`

  // Rest of proxy implementation
}

生产部署

生产环境中的常见问题：

未应用一次性随机数：确保您的 proxy 在所有必要的路由上运行
静态资源被阻止：验证您的 CSP 允许 Next.js 静态资源
第三方脚本：将必要的域添加到您的 CSP 策略中

故障排除

第三方脚本

App Router Only

当将第三方脚本与 CSP 一起使用时：

tsx

import { GoogleTagManager } from '@next/third-parties/google'
import { headers } from 'next/headers'

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const nonce = (await headers()).get('x-nonce')

  return (
    <html lang="en">
      <body>
        {children}
        <GoogleTagManager gtmId="GTM-XYZ" nonce={nonce} />
      </body>
    </html>
  )
}

jsx

import { GoogleTagManager } from '@next/third-parties/google'
import { headers } from 'next/headers'

export default async function RootLayout({ children }) {
  const nonce = (await headers()).get('x-nonce')

  return (
    <html lang="en">
      <body>
        {children}
        <GoogleTagManager gtmId="GTM-XYZ" nonce={nonce} />
      </body>
    </html>
  )
}

Pages Router Only

当将第三方脚本与 CSP 一起使用时，请确保您添加了必要的域并传递了一次性随机数：

tsx

import type { AppProps } from 'next/app'
import Script from 'next/script'

export default function App({ Component, pageProps }: AppProps) {
  const nonce = pageProps.nonce

  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://www.googletagmanager.com/gtag/js"
        strategy="afterInteractive"
        nonce={nonce}
      />
    </>
  )
}

jsx

import Script from 'next/script'

export default function App({ Component, pageProps }) {
  const nonce = pageProps.nonce

  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://www.googletagmanager.com/gtag/js"
        strategy="afterInteractive"
        nonce={nonce}
      />
    </>
  )
}

更新您的 CSP 以允许第三方域：

typescript

const cspHeader = `
  default-src 'self';
  script-src 'self' 'nonce-${nonce}' 'strict-dynamic' https://www.googletagmanager.com;
  connect-src 'self' https://www.google-analytics.com;
  img-src 'self' data: https://www.google-analytics.com;
`

javascript

const cspHeader = `
  default-src 'self';
  script-src 'self' 'nonce-${nonce}' 'strict-dynamic' https://www.googletagmanager.com;
  connect-src 'self' https://www.google-analytics.com;
  img-src 'self' data: https://www.google-analytics.com;
`

常见 CSP 违规

内联样式：使用支持一次性随机数的 CSS-in-JS 库或将样式移动到外部文件
动态导入：确保您的 script-src 策略中允许动态导入
WebAssembly：如果使用 WebAssembly，请添加 'wasm-unsafe-eval'
Service Worker：为 Service Worker 脚本添加适当的策略

版本历史

版本	变更
`v14.0.0`	添加了基于哈希的 CSP 的实验性 SRI 支持
`v13.4.20`	推荐用于正确的一次性随机数处理和 CSP 请求头解析。

文档导航

一次性随机数 (Nonces)

为什么要使用一次性随机数？

使用 Proxy 添加一次性随机数

一次性随机数在 Next.js 中的工作原理

强制动态渲染

读取一次性随机数

静态渲染与动态渲染与 CSP

动态渲染要求

性能影响

何时使用一次性随机数

不使用一次性随机数

子资源完整性（实验性）

SRI 工作原理

启用 SRI

CSP 与 SRI 配置

SRI 相对于一次性随机数的优势

SRI 的局限性

开发与生产环境考虑

开发环境

生产部署

故障排除

第三方脚本

常见 CSP 违规

版本历史

一次性随机数 (Nonces)

为什么要使用一次性随机数？

使用 Proxy 添加一次性随机数

一次性随机数在 Next.js 中的工作原理

强制动态渲染

读取一次性随机数

静态渲染与动态渲染与 CSP

动态渲染要求

性能影响

何时使用一次性随机数

不使用一次性随机数

子资源完整性（实验性）

SRI 工作原理

启用 SRI

CSP 与 SRI 配置

SRI 相对于一次性随机数的优势

SRI 的局限性

开发与生产环境考虑

开发环境

生产部署

故障排除

第三方脚本

常见 CSP 违规

版本历史