NNext.js 中文网 GitHub

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

了解如何为你的 Next.js 应用设置内容安全策略(CSP)。

内容安全策略(CSP) 对于保护你的 Next.js 应用程序免受跨站脚本(XSS)、点击劫持和其他代码注入攻击等各种安全威胁非常重要。

通过使用 CSP,开发者可以指定内容来源、脚本、样式表、图片、字体、对象、媒体(音频、视频)、iframe 等允许使用的来源。

<details> <summary>示例</summary>

</details>

Nonce#

Nonce 是为一次性使用而创建的唯一随机字符串。它与 CSP 结合使用,可选择性地允许某些内联脚本或样式执行,从而绕过严格的 CSP 指令。

为什么要使用 nonce?#

CSP 可以阻止内联和外部脚本以防止攻击。Nonce 使你可以安全地允许特定脚本运行——前提是它们包含匹配的 nonce 值。

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

使用 Proxy 添加 nonce#

Proxy 使你能够在页面渲染之前添加标头并生成 nonce。

每次查看页面时,都应生成一个新的 nonce。这意味着你必须使用动态渲染来添加 nonce。

例如:

小知识:在开发环境中,需要 'unsafe-eval',因为 React 使用 eval 来提供增强的调试信息,例如在浏览器中重建服务端错误堆栈。生产环境不需要 unsafe-eval。默认情况下,React 和 Next.js 在生产环境中都不使用 eval。

proxy.ts
import { NextRequest, NextResponse } from 'next/server'

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' '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;
`
  // 替换换行符和空格
  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.js
import { NextResponse } from 'next/server'

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' '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;
`
  // 替换换行符和空格
  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 标头的静态资源。

proxy.ts
export const config = {
  matcher: [
    /*
     * 匹配所有请求路径,除了以下开头的路径:
     * - api(API 路由)
     * - _next/static(静态文件)
     * - _next/image(图片优化文件)
     * - favicon.ico(favicon 文件)
     */
    {
      source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
  ],
}
proxy.js
export const config = {
  matcher: [
    /*
     * 匹配所有请求路径,除了以下开头的路径:
     * - api(API 路由)
     * - _next/static(静态文件)
     * - _next/image(图片优化文件)
     * - favicon.ico(favicon 文件)
     */
    {
      source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
  ],
}

Nonce 在 Next.js 中如何工作#

要使用 nonce,你的页面必须动态渲染。这是因为 Next.js 在服务端渲染期间根据请求中存在的 CSP 标头应用 nonce。静态页面在构建时生成,此时不存在请求或响应标头——因此无法注入 nonce。

以下是对动态渲染页面中 nonce 支持的工作方式:

  1. Proxy 生成 nonce:你的 proxy 为请求创建唯一的 nonce,将其添加到 Content-Security-Policy 标头中,并在自定义的 x-nonce 标头中设置它。
  2. Next.js 提取 nonce:在渲染期间,Next.js 解析 Content-Security-Policy 标头,并使用 'nonce-{value}' 模式提取 nonce。
  3. 自动应用 Nonce:Next.js 将 nonce 附加到:
    • 框架脚本(React、Next.js 运行时)
    • 特定于页面的 JavaScript 包
    • Next.js 生成的内联样式和脚本
    • 任何使用 nonce 属性的 <Script> 组件

由于这种自动行为,你无需为每个标签手动添加 nonce。

强制动态渲染#

如果你使用 nonce,可能需要显式选择让页面进行动态渲染:

app/page.tsx
import { connection } from 'next/server'

export default async function Page() {
  // 等待传入请求以渲染此页面
  await connection()
  // 你的页面内容
}
app/page.jsx
import { connection } from 'next/server'

export default async function Page() {
  // 等待传入请求以渲染此页面
  await connection()
  // 你的页面内容
}

读取 nonce#

你可以使用 getServerSideProps 将 nonce 提供给页面:

pages/index.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 } }
}
pages/index.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 中访问 nonce:

pages/_document.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
pages/_document.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

你可以使用 headers 从 Server Component 中读取 nonce:

app/page.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}
    />
  )
}
app/page.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 时的静态渲染与动态渲染#

使用 nonce 会对 Next.js 应用程序的渲染方式产生重要影响:

动态渲染要求#

当你在 CSP 中使用 nonce 时,所有页面都必须动态渲染。这意味着:

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

性能影响#

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

  • 页面初始加载变慢:页面必须在每次请求时生成
  • 服务器负载增加:每个请求都需要服务端渲染
  • 无 CDN 缓存:默认情况下,动态页面无法在边缘缓存
  • 更高的托管成本:动态渲染需要更多服务器资源

何时使用 nonce#

在以下情况下考虑使用 nonce:

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

不使用 Nonce#

对于不需要 nonce 的应用程序,你可以直接在 next.config.js 文件中设置 CSP 标头:

next.config.js
const isDev = process.env.NODE_ENV === 'development'

const cspHeader = `
    default-src 'self';
    script-src 'self' 'unsafe-inline'${isDev ? " 'unsafe-eval'" : ''};
    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, ''),
          },
        ],
      },
    ]
  },
}

子资源完整性(实验性)#

作为 nonce 的替代方案,Next.js 提供了对使用子资源完整性(Subresource Integrity,SRI)的基于哈希的 CSP 的实验性支持。这种方法使你能够保持静态生成,同时仍然拥有严格的 CSP。

小知识:此功能是实验性的,仅适用于 App Router 应用程序。

SRI 如何工作#

SRI 不使用 nonce,而是在构建时为你的 JavaScript 文件生成加密哈希。这些哈希作为 integrity 属性添加到脚本标签中,使浏览器能够验证文件在传输过程中未被修改。

启用 SRI#

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

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

module.exports = nextConfig

使用 SRI 的 CSP 配置#

启用 SRI 后,你可以继续使用现有的 CSP 策略。SRI 通过向你的资源添加 integrity 属性独立工作:

小知识:对于动态渲染场景,如果需要,你仍然可以使用 proxy 生成 nonce,将 SRI integrity 属性和基于 nonce 的 CSP 方法结合使用。

next.config.js
const isDev = process.env.NODE_ENV === 'development'

const cspHeader = `
    default-src 'self';
    script-src 'self'${isDev ? " 'unsafe-eval'" : ''};
    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 相较于 nonce 的优势#

  • 静态生成:页面可以静态生成并缓存
  • CDN 兼容性:静态页面可与 CDN 缓存配合使用
  • 更好的性能:无需对每个请求进行服务端渲染
  • 构建时安全性:哈希在构建时生成,确保完整性

SRI 的局限性#

  • 实验性:功能可能会更改或移除
  • 仅支持 App Router:Pages Router 不支持
  • 仅限构建时:无法处理动态生成的脚本

开发与生产环境的注意事项#

CSP 的实现在开发环境和生产环境中有所不同:

开发环境#

在开发环境中,你需要启用 'unsafe-eval',因为 React 使用 eval 来提供增强的调试信息,例如在浏览器中重建服务端错误堆栈,以向你显示错误在服务端产生的位置:

proxy.ts
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;
`

  // proxy 实现的其余部分
}
proxy.js
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;
`

  // proxy 实现的其余部分
}

生产部署#

生产环境中的常见问题:

  • 未应用 Nonce:确保你的 proxy 在所有必要的路由上运行
  • 静态资源被阻止:验证你的 CSP 允许 Next.js 静态资源
  • 第三方脚本:将必要的域名添加到你的 CSP 策略中

故障排除#

第三方脚本#

在 CSP 中使用第三方脚本时:

app/layout.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>
  )
}
app/layout.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>
  )
}

在 CSP 中使用第三方脚本时,请确保添加必要的域名并传递 nonce:

pages/_app.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}
      />
    </>
  )
}
pages/_app.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 以允许第三方域名:

proxy.ts
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;
`
proxy.js
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 违规#

  1. 内联样式:使用支持 nonce 的 CSS-in-JS 库,或将样式移到外部文件
  2. 动态导入:确保你的 script-src 策略允许动态导入
  3. WebAssembly:如果使用 WebAssembly,请添加 'wasm-unsafe-eval'
  4. Service Worker:为 service worker 脚本添加适当的策略

版本历史#

版本变更
v16.2.0为 Turbopack 添加了实验性 SRI 支持
v14.0.0添加了针对基于哈希的 CSP 的实验性 SRI 支持
v13.4.20推荐用于正确的 nonce 处理和 CSP 标头解析。
Next.js 中文网