实验性内容安全策略 (CSP)

类型： boolean | object
默认值： false

添加于： astro@5.9.0

启用对内容安全策略 (CSP)的支持，通过控制文档允许加载哪些资源来帮助最小化某些类型的安全威胁。这为防范跨站脚本 (XSS)攻击提供了额外的保护。

默认情况下，启用此功能会为 Astro 处理和打包脚本和样式的过程增加额外的安全性，并允许你进一步配置这些以及其他内容类型。

这个实验性的 CSP 功能有一些限制。内联脚本不被直接支持，但你可以为外部和内联脚本提供自己的哈希值。使用 <ClientRouter /> 的 Astro 视图过渡不被支持，但如果你没有使用 Astro 对原生视图过渡和导航 API 的增强功能，你可以考虑迁移到浏览器原生的 View Transition API。

要启用此功能，请在你的 Astro 配置中添加实验性标志

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: true
  }
});

启用后，Astro 会在每个页面的 <head> 元素内添加一个 <meta> 元素。

该元素将具有 http-equiv="content-security-policy" 属性，并且 content 属性将根据页面中使用的脚本和样式为 script-src 和 style-src 指令提供值。

<head>
  <meta
    http-equiv="content-security-policy"
    content="
      script-src 'self' 'sha256-somehash';
      style-src 'self' 'sha256-somehash';
    "
  >
</head>

配置

你可以通过使用包含附加选项的配置对象来启用此功能，从而进一步自定义 <meta> 元素。

`算法`

类型： 'SHA-256' | 'SHA-512' | 'SHA-384'
默认值： 'SHA-256'

添加于： astro@5.9.0

在生成 Astro 发出的样式和脚本的哈希值时使用的哈希函数。

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      algorithm: 'SHA-512'
    }
  }
});

`指令`

类型： CspDirective[]
默认值： []

添加于： astro@5.9.0

一个CSP 指令列表，用于为特定内容类型定义有效来源。

虽然 Astro 需要控制 script-src 和 style-src 指令，但可以使用 csp.directives 字段来控制其他 CSP 指令。这些指令会被添加到所有页面。它接受一个类型安全的指令列表

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      directives: [
        "default-src 'self'",
        "img-src 'self' https://images.cdn.example.com"
      ]
    }
  }
});

构建后，<meta> 元素会将你的指令与 Astro 的默认指令一起添加到 content 值中

<meta
  http-equiv="content-security-policy"
  content="
    default-src 'self';
    img-src 'self' 'https://images.cdn.example.com';
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`styleDirective` 和 `scriptDirective`

类型： object
默认值： {}

添加于： astro@5.9.0

配置对象，允许你使用 resources 属性覆盖 style-src 和 script-src 指令的默认来源，或提供要渲染的额外哈希值。

这些属性会添加到所有页面，并且会完全覆盖 Astro 的默认资源，而不是添加到它们之上。因此，你必须明确指定任何你希望包含的默认值。

`资源`

类型： string[]
默认值： []

添加于： astro@5.9.0

script-src 和 style-src 指令的有效来源列表。

script-src 和 style-src 指令默认由 Astro 处理，并使用 'self' 资源。这意味着脚本和样式只能由当前主机（通常是当前网站）下载。

要覆盖默认来源，你可以提供一个资源列表。默认情况下，这个列表将不包括 'self'，如果你希望保留它，就必须在此列表中包含它。这些资源会被添加到所有页面。

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      styleDirective: {
        resources: [
          "'self'",
          "https://styles.cdn.example.com"
        ]
      },
      scriptDirective: {
        resources: [
          "https://cdn.example.com"
        ]
      }
    }
  }
});

构建后，<meta> 元素将改为把你的来源应用到 style-src 和 script-src 指令

<head>
  <meta
    http-equiv="content-security-policy"
    content="
      script-src https://cdn.example.com 'sha256-somehash';
      style-src 'self' https://styles.cdn.example.com 'sha256-somehash';
    "
  >
</head>

`哈希`

类型： CspHash[]
默认值： []

添加于： astro@5.9.0

要渲染的额外哈希值列表。

如果你有非 Astro 生成的外部脚本或样式，或内联脚本，此配置选项允许你提供要渲染的额外哈希值。

你必须提供以 sha384-、sha512- 或 sha256- 开头的哈希值。其他值将导致验证错误。这些哈希值会被添加到所有页面。

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      styleDirective: {
        hashes: [
          "sha384-styleHash",
          "sha512-styleHash",
          "sha256-styleHash"
        ]
      },
      scriptDirective: {
        hashes: [
          "sha384-scriptHash",
          "sha512-scriptHash",
          "sha256-scriptHash"
        ]
      }
    }
  }
});

构建后，<meta> 元素将在 script-src 和 style-src 指令中包含你提供的额外哈希值

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha384-scriptHash' 'sha512-scriptHash' 'sha256-scriptHash' 'sha256-generatedByAstro';
    style-src 'self' 'sha384-styleHash' 'sha512-styleHash' 'sha256-styleHash' 'sha256-generatedByAstro';
  "
>

`strictDynamic`

类型： boolean
默认值： false

添加于： astro@5.9.0

启用strict-dynamic 关键字以支持脚本的动态注入。

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      scriptDirective: {
        strictDynamic: true
      }
    }
  }
});

运行时 API

你可以通过 .astro 组件内的 Astro 全局对象，或端点和中间件中的 APIContext 类型，使用运行时 API 逐页自定义 <meta> 元素。

`insertDirective`

类型： (directive: CspDirective) => void

添加于： astro@5.9.0

向当前页面添加单个指令。你可以多次调用此方法以添加其他指令。

---
Astro.insertDirective("default-src 'self'");
Astro.insertDirective("img-src 'self' https://images.cdn.example.com");
---

构建后，该独立页面的 <meta> 元素将把你添加的指令与现有的 script-src 和 style-src 指令结合起来

<meta
  http-equiv="content-security-policy"
  content="
    default-src 'self';
    img-src 'self' https://images.cdn.example.com;
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`insertStyleResource`

类型： (resource: string) => void

添加于： astro@5.9.0

为 style-src 指令插入一个新资源。

---
Astro.insertStyleResource("https://styles.cdn.example.com");
---

构建后，该独立页面的 <meta> 元素会将你的来源添加到默认的 style-src 指令中

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash';
    style-src https://styles.cdn.example.com 'sha256-somehash';
  "
>

`insertStyleHash`

类型： (hash: CspHash) => void

添加于： astro@5.9.0

向 style-src 指令添加一个新的哈希值。

---
Astro.insertStyleHash("sha512-styleHash");
---

构建后，该独立页面的 <meta> 元素会将你的哈希值添加到默认的 style-src 指令中

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash' 'sha512-styleHash';
  "
>

`insertScriptResource`

类型： (resource: string) => void

添加于： astro@5.9.0

为 script-src 指令插入一个新的有效来源。

---
Astro.insertScriptResource("https://scripts.cdn.example.com");
---

构建后，该独立页面的 <meta> 元素会将你的来源添加到默认的 script-src 指令中

<meta
  http-equiv="content-security-policy"
  content="
    script-src https://scripts.cdn.example.com 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`insertScriptHash`

类型： (hash: CspHash) => void

添加于： astro@5.9.0

向 script-src 指令添加一个新的哈希值。

---
Astro.insertScriptHash("sha512-scriptHash");
---

构建后，该独立页面的 <meta> 元素会将你的哈希值添加到默认的 script-src 指令中

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash' 'sha512-styleHash';
    style-src 'self' 'sha256-somehash';
  "
>

贡献社区赞助

实验性内容安全策略 (CSP)

配置

算法

指令

styleDirective 和 scriptDirective

资源

哈希

strictDynamic

运行时 API

insertDirective

insertStyleResource

insertStyleHash

insertScriptResource

insertScriptHash

`算法`

`指令`

`styleDirective` 和 `scriptDirective`

`资源`

`哈希`

`strictDynamic`

`insertDirective`

`insertStyleResource`

`insertStyleHash`

`insertScriptResource`

`insertScriptHash`