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

类型：boolean | object
默认：false

¥Type: boolean | object
Default: false

Added in: astro@5.9.0

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

¥Enables support for Content Security Policy (CSP) to help minimize certain types of security threats by controlling which resources a document is allowed to load. This provides additional protection against cross-site scripting (XSS) attacks.

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

¥Enabling this feature adds additional security to Astro’s handling of processed and bundled scripts and styles by default, and allows you to further configure these, and additional, content types.

此实验性 CSP 功能有一些限制。内联脚本并非开箱即用，但你可以使用提供你自己的哈希值来支持外部和内联脚本。不支持使用 <ClientRouter /> 的 Astro 的视图转换，但如果你不使用 Astro 对原生视图转换和导航 API 的增强功能，则可以改用考虑迁移到浏览器原生的 View Transition API。

¥This experimental CSP feature has some limitations. Inline scripts are not supported out of the box, but you can provide your own hashes for external and inline scripts. Astro’s view transitions using the <ClientRouter /> are not supported, but you can consider migrating to the browser native View Transition API instead if you are not using Astro’s enhancements to the native View Transitions and Navigation APIs.

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

¥To enable this feature, add the experimental flag in your Astro config:

import { defineConfig } from 'astro/config';

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

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

¥When enabled, Astro will add a <meta> element inside the <head> element of each page.

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

¥This element will have the http-equiv="content-security-policy" attribute, and the content attribute will provide values for the script-src and style-src directives based on the script and styles used in the page.

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

配置

¥Configuration

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

¥You can further customize the <meta> element by enabling this feature with a configuration object that includes additional options.

`algorithm`

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

¥Type: 'SHA-256' | 'SHA-512' | 'SHA-384'
Default: 'SHA-256'

Added in: astro@5.9.0

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

¥The hash function to use when generating the hashes of the styles and scripts emitted by Astro.

import { defineConfig } from 'astro/config';

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

`directives`

类型：CspDirective[]
默认：[]

¥Type: CspDirective[]
Default: []

Added in: astro@5.9.0

定义特定内容类型有效来源的 CSP 指令列表。

¥A list of CSP directives that defines valid sources for specific content types.

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

¥While Astro needs to control the script-src and style-src directives, it is possible to control other CSP directives using the csp.directives field. These directives are added to all pages. It accepts a list of type-safe directives:

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 值中：

¥After the build, the <meta> element will add your directives into the content value alongside Astro’s default directives:

<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`

¥styleDirective and scriptDirective

类型：object
默认：{}

¥Type: object
Default: {}

Added in: astro@5.9.0

配置对象允许你使用 resources 属性覆盖 style-src 和 script-src 指令的默认源，或提供其他要渲染的 hashes。

¥Configuration objects that allow you to override the default sources for the style-src and script-src directives with the resources property, or to provide additional hashes to be rendered.

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

¥These properties are added to all pages and completely override Astro’s default resources, not add to them. Therefore, you must explicitly specify any default values that you want to be included.

`resources`

类型：string[]
默认：[]

¥Type: string[]
Default: []

Added in: astro@5.9.0

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

¥A list of valid sources for the script-src and style-src directives.

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

¥The script-src and style-src directives are handled by Astro by default, and use the 'self' resource. This means that scripts and styles can only be downloaded by the current host (usually the current website).

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

¥To override the default source, you can provide a list of resources instead. This will not include 'self' by default, and must be included in this list if you wish to keep it. These resources are added to all pages.

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 指令：

¥After the build, the <meta> element will instead apply your sources to the style-src and script-src directives:

<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>

`hashes`

类型：CspHash[]
默认：[]

¥Type: CspHash[]
Default: []

Added in: astro@5.9.0

需要渲染的其他哈希值列表。

¥A list of additional hashes to be rendered.

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

¥If you have external scripts or styles that aren’t generated by Astro, or inline scripts, this configuration option allows you to provide additional hashes to be rendered.

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

¥You must provide hashes that start with sha384-, sha512- or sha256-. Other values will cause a validation error. These hashes are added to all pages.

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 指令中：

¥After the build, the <meta> element will include your additional hashes in the script-src and style-src directives:

<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

¥Type: boolean
Default: false

Added in: astro@5.9.0

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

¥Enables the strict-dynamic keyword to support the dynamic injection of scripts.

import { defineConfig } from 'astro/config';

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

运行时 API

¥Runtime APIs

你可以通过 .astro 组件内 Astro 全局变量或端点和中间件中的 APIContext 类型提供的运行时 API，为每个页面自定义 <meta> 元素。

¥You can customize the <meta> element per page via runtime APIs available from the Astro global inside .astro components, or the APIContext type in endpoints and middleware.

`insertDirective`

类型：(directive: CspDirective) => void

¥Type: (directive: CspDirective) => void

Added in: astro@5.9.0

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

¥Adds a single directive to the current page. You can call this method multiple times to add additional directives.

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

构建完成后，此单独页面的 <meta> 元素会将你的附加指令与现有的 script-src 和 style-src 指令合并：

¥After the build, the <meta> element for this individual page will incorporate your additional directives alongside the existing script-src and style-src directives:

<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

¥Type: (resource: string) => void

Added in: astro@5.9.0

插入一个用于 style-src 指令的新资源。

¥Inserts a new resource to be used for the style-src directive.

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

构建完成后，此单独页面的 <meta> 元素会将你的源代码添加到默认的 style-src 指令中：

¥After the build, the <meta> element for this individual page will add your source to the default style-src directive:

<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

¥Type: (hash: CspHash) => void

Added in: astro@5.9.0

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

¥Adds a new hash to the style-src directive.

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

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

¥After the build, the <meta> element for this individual page will add your hash to the default style-src directive:

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

`insertScriptResource`

类型：(resource: string) => void

¥Type: (resource: string) => void

Added in: astro@5.9.0

插入一个用于 script-src 指令的新的有效源。

¥Inserts a new valid source to be used for the script-src directive.

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

构建完成后，此单独页面的 <meta> 元素会将你的源代码添加到默认的 script-src 指令中：

¥After the build, the <meta> element for this individual page will add your source to the default script-src directive:

<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

¥Type: (hash: CspHash) => void

Added in: astro@5.9.0

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

¥Adds a new hash to the script-src directive.

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

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

¥After the build, the <meta> element for this individual page will add your hash to the default script-src directive:

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

Astro v5.10 中文网 - 粤ICP备13048890号

Nodejs.cn 旗下网站

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

配置

algorithm

directives

styleDirective 和 scriptDirective

resources

hashes

strictDynamic

运行时 API

insertDirective

insertStyleResource

insertStyleHash

insertScriptResource

insertScriptHash

`algorithm`

`directives`

`styleDirective` 和 `scriptDirective`

`resources`

`hashes`

`strictDynamic`

`insertDirective`

`insertStyleResource`

`insertStyleHash`

`insertScriptResource`

`insertScriptHash`