如何为你的 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。
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
}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 标头的静态资源。
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' },
],
},
],
}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 支持的工作方式:
- Proxy 生成 nonce:你的 proxy 为请求创建唯一的 nonce,将其添加到
Content-Security-Policy标头中,并在自定义的x-nonce标头中设置它。 - Next.js 提取 nonce:在渲染期间,Next.js 解析
Content-Security-Policy标头,并使用'nonce-{value}'模式提取 nonce。 - 自动应用 Nonce:Next.js 将 nonce 附加到:
- 框架脚本(React、Next.js 运行时)
- 特定于页面的 JavaScript 包
- Next.js 生成的内联样式和脚本
- 任何使用
nonce属性的<Script>组件
由于这种自动行为,你无需为每个标签手动添加 nonce。
强制动态渲染#
如果你使用 nonce,可能需要显式选择让页面进行动态渲染:
import { connection } from 'next/server'
export default async function Page() {
// 等待传入请求以渲染此页面
await connection()
// 你的页面内容
}import { connection } from 'next/server'
export default async function Page() {
// 等待传入请求以渲染此页面
await connection()
// 你的页面内容
}读取 nonce#
你可以使用 getServerSideProps 将 nonce 提供给页面:
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 } }
}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:
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 MyDocumentimport 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:
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}
/>
)
}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 标头:
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 中:
/** @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 方法结合使用。
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 来提供增强的调试信息,例如在浏览器中重建服务端错误堆栈,以向你显示错误在服务端产生的位置:
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 实现的其余部分
}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 中使用第三方脚本时:
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>
)
}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:
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}
/>
</>
)
}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 以允许第三方域名:
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;
`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 违规#
- 内联样式:使用支持 nonce 的 CSS-in-JS 库,或将样式移到外部文件
- 动态导入:确保你的 script-src 策略允许动态导入
- WebAssembly:如果使用 WebAssembly,请添加
'wasm-unsafe-eval' - Service Worker:为 service worker 脚本添加适当的策略
版本历史#
| 版本 | 变更 |
|---|---|
v16.2.0 | 为 Turbopack 添加了实验性 SRI 支持 |
v14.0.0 | 添加了针对基于哈希的 CSP 的实验性 SRI 支持 |
v13.4.20 | 推荐用于正确的 nonce 处理和 CSP 标头解析。 |