配置参考

下面的参考资料涵盖了 Astro 所有支持的配置选项。要了解更多关于配置 Astro 的信息，请阅读我们的配置 Astro 指南。

import { defineConfig } from 'astro/config'

export default defineConfig({
  // 你的配置在这里...
})

顶层选项

site

类型：string

你最终部署的链接。Astro 会使用这个完整的链接来生成网站地图和最终构建的规范链接。强烈建议你设置这个配置项，以获得 Astro 最佳体验。

{
  site: 'https://www.my-site.dev'
}

base

类型：string

你要部署到的基本路径。Astro 在开发过程中会匹配这个路径名，这样你的开发环境就会尽可能地与你的构建环境匹配。在下面的例子中，astro dev 会在 /docs 处启动你的服务器。

{
  base: '/docs'
}

当使用这个选项时，你所有的静态资源导入和 URL 都需要添加 base 作为前缀。你可以通过 import.meta.env.BASE_URL 访问这个值。

import.meta.env.BASE_URL 的值将由你的 trailingSlash 配置所决定，无论你为 base 设置了什么值。

如果设置了 trailingSlash: "always"，则始终包含尾部斜杠。如果设置了 trailingSlash: "never"，即使 base 包含斜杠，BASE_URL 也不会包含尾部斜杠。

此外，Astro 在将 config.base 的配置值提供给集成之前会进行内部操作。由集成读取的 config.base 值也同样由你的 trailingSlash 配置决定。

在下面的示例中，在处理时 import.meta.env.BASE_URL 和 config.base 的值都将是 /docs：

{
   base: '/docs/',
   trailingSlash: "never"
}

在下面的示例中，在处理时 import.meta.env.BASE_URL 和 config.base 的值都将是 /docs/：

{
   base: '/docs',
   trailingSlash: "always"
}

trailingSlash

类型：'always' | 'never' | 'ignore'
默认值：'ignore'

设置开发服务器的路由匹配行为。从以下选项中选择：

'always' - 只匹配包含尾部斜线的链接（例如：/foo/）。
'never' - 不匹配包含尾部斜线的链接（例如：/foo）。
'ignore'- 匹配链接，不管是否存在尾部的 /。

如果你的生产主机对尾部斜杠的工作或不工作有严格的处理方式，请使用该配置选项。

如果你希望自己更严格一些，那么你也可以设置这个选项，这样在开发过程中，无论是否有尾部斜杠的 URL 都不会工作。

{
  // 示例：在开发过程中要求有尾部斜线
  trailingSlash: 'always'
}

另见：

build.format

redirects

类型： Record.<string, RedirectConfig>
默认值： {}

添加于： astro@2.9.0

指定重定向的映射关系。其中键为要匹配的路由，值为重定向的路径。

你可以重定向静态和动态路由，但只能重定向到相同类型的路由。例如，你不能有一个 '/article': '/blog/[...slug]' 的重定向。

{
  redirects: {
    '/old': '/new',
    '/blog/[...slug]': '/articles/[...slug]',
  }
}

对于未安装适配器的静态生成站点，这将生成一个使用 <meta http-equiv="refresh"> 标签的客户端重定向，并且不支持状态码。

而使用 SSR 或以 output: static 模式使用静态适配器时，则支持状态码。

默认情况下，Astro 将以 301 的状态对重定向的 GET 请求进行处理，并对其他请求方法使用 308 的状态。

你可以使用重定向配置中的对象自定义重定向状态码：

{
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
}

output

类型：'static' | 'server' | 'hybrid'
默认值：'static'

指定构建的输出目标。

static- 构建静态网站，部署到任何静态托管服务器上；
server - 构建应用，部署到支持 SSR（服务器端渲染）的托管服务器上；
hybrid - 构建包含少量服务端渲染页面的静态网站。

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static'
})

另见：

adapter

adapter

类型：AstroIntegration

使用构建适配器将其部署到你最喜爱的服务器、无服务器或边缘主机。导入我们的第一方适配器 Netlify、Vercel，以及更多的适配器来使用 Astro SSR。

有关 SSR 的更多信息，请参见我们的服务器端渲染指南，以及我们的部署指南以获得完整的主机列表。

import netlify from '@astrojs/netlify';
{
  // 示例：使用 Netlify 无服务器部署构建
  adapter: netlify(),
}

另见：

output

integrations

类型： AstroIntegration[]

用自定义集成来扩展 Astro 功能。你可以用集成来添加框架支持（如 Solid.js）、新功能（如站点地图）和新库支持（如 Partytown）。

请阅读我们的集成指南，以帮助开始使用 Astro 集成。

import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // 示例：添加 React + Tailwind 支持
  integrations: [react(), tailwind()]
}

root

类型：string
CLI：--root
默认值："." (当前工作文件夹)

只有当你在项目根目录以外的目录下运行 astro CLI 命令时，你才应该提供该选项。通常，这个选项是通过 CLI 而不是 Astro 配置文件提供的，因为 Astro 需要知道项目根目录才能找到配置文件。

如果提供相对路径（例如：--root: './my-project'），Astro 会根据你当前的工作目录进行解析。

示例

{
  root: './my-project-directory'
}

$ astro build --root ./my-project-directory

srcDir

类型：string
默认值："./src"

设置 Astro 将读取网站的目录。

这个值可以是绝对路径，也可以是相对路径。

{
  srcDir: './www'
}

publicDir

类型：string
默认值："./public"

设置静态资源目录。这个目录下的文件在开发过程中被提供给 /，在构建过程中被复制到构建目录。这些文件总是按原样提供或复制的，没有转换或捆绑。

这个值可以是绝对路径，也可以是相对路径。

{
  publicDir: './my-custom-publicDir-directory'
}

outDir

类型：string
默认值："./dist"

设置 astro build 将你的最终构建写入的目录。

这个值可以是绝对路径，也可以是相对路径。

{
  outDir: './my-custom-build-directory'
}

另见：

build.server

cacheDir

类型： string
默认值： "./node_modules/.astro"

设置用于缓存构建产物的目录。该目录中的文件将在后续构建中使用，以加快构建时间。

这个值可以是绝对路径，也可以是相对路径。

{
  cacheDir: './my-custom-cache-directory'
}

compressHTML

类型： boolean
默认值： true

这是一个用于缩小 HTML 输出并减少 HTML 文件大小的选项。默认情况下，Astro 会从 .astro 组件中移除所有空格，包括换行符。这个优化会在开发模式和最终构建中生效。

要禁用 HTML 压缩，请将 compressHTML 标志设置为 false。

{
  compressHTML: false
}

scopedStyleStrategy

类型： 'where' | 'class' | 'attribute'
默认值： 'attribute'

添加于： astro@2.4

指定 Astro 组件内部样式作用范围。可选项包括：

'where' - 使用 :where 选择器，不会增加特异性。
'class' - 使用基于类的选择器，会增加 +1 的特异性。
'attribute' - 使用 data- 属性，不会增加特异性。

使用 'class' 可以确保 Astro 组件内的元素选择器覆盖全局样式默认值（例如来自全局样式表）。

使用 'where' 可以更好地控制特异性，但需要使用更高特异性的选择器、层级和其他工具来控制应用的选择器。

使用 'attribute' 在你操作元素的 class 属性时很有用，这样你就可以避免你自己的样式逻辑和 Astro 的样式应用之间的冲突。

vite

类型： ViteUserConfig

传递额外的配置选项给 Vite。适用于需要使用一些 Astro 不支持的高级配置。

在 vitejs.dev 上查看完整的 vite 配置对象文档。

示例

{
  vite: {
    ssr: {
      // 示例；如果需要的话，可以强制破坏性包跳过 SSR 处理
      external: ['broken-npm-package'],
    }
  }
}

{
  vite: {
    // 示例：直接在 Astro 项目中添加自定义 Vite 插件
    plugins: [myPlugin()],
  }
}

构建选项

build.format

类型：('file' | 'directory' | 'preserve')
默认值：'directory'

控制每个页面的输出文件格式。这个值可能会由适配器帮你设置：

'file'：Astro 将为每个路由生成一个 HTML 文件。（例如：src/pages/about.astro 和 src/pages/about/index.astro 都会打包成 /about.html 文件）
'directory'：Astro 将生成一个目录，其中包含每个页面的嵌套的 index.html 文件。 (例如：src/pages/about.astro 和 src/pages/about/index.astro 都会打包成 /about/index.html 文件)
'preserve'：Astro 将根据你的源文件夹中的文件生成 HTML 文件。 (例如：src/pages/about.astro 生成 /about.html，src/pages/about/index.astro 生成 /about/index.html)

{
  build: {
    // 示例：在构建过程中生 成`page.html` 而不是 `page/index.html`。
    format: 'file'
  }
}

对 Astro.url 的影响

设置 build.format 可以控制 Astro.url 在构建过程中被设置成什么。当它是：

directory - Astro.url.pathname 将包括一个尾部斜杠，以模仿文件夹行为；例如 /foo/。
file - Astro.url.pathname 将包括 .html，即/foo.html。

这意味着当你使用 new URL('./relative', Astro.url) 创建相对的连接时，开发和构建会得到一致的行为。

为了避免开发环境中尾部斜杠行为的不一致性，你可以根据构建格式将 trailingSlash 选项限制为 'always' 或 'never'：

directory - 设置 trailingSlash: 'always'
file - 设置 trailingSlash: 'never'

build.client

类型：string
默认值：'./dist/client'

仅当设置output: 'server' 或 output: 'hybrid'时，控制你的客户端 CSS 和 JavaScript 的输出文件夹。 outDir 控制代码的构建位置。

这个值是相对于 outDir 的。

{
  output: 'server', // 或者 'hybrid'
  build: {
    client: './client'
  }
}

build.server

类型：string
默认值：'./dist/server'

当构建为 SSR 时控制服务器 JavaScript 的输出目录。

这个值是相对于 outDir 的。

{
  build: {
    server: './server'
  }
}

build.assets

类型：string
默认值：'_astro'

添加于： astro@2.0.0

指定 Astro 生成的资源（例如打包的 JS 和 CSS）在构建输出中的目录。

{
  build: {
    assets: '_custom'
  }
}

另见：

outDir

build.assetsPrefix

类型： string | Record.<string, string>
默认值： undefined

添加于： astro@2.2.0

指定 Astro 生成的资源链接的前缀。如果资源与当前站点来自不同的域，则可以使用此选项。

这需要将你本地的 ./dist/_astro 文件夹中的资源上传到远程域名下相应的 /_astro/ 文件夹中。要重命名 _astro 路径，请在 build.assets 中指定一个新的目录。

要获取上传到同一域名下的所有资源（例如 https://cdn.example.com/_astro/...），请将 assetsPrefix 设置为根域名的字符串（不管你的 base 配置如何）：

{
  build: {
    assetsPrefix: 'https://cdn.example.com'
  }
}

新增于： astro@4.5.0

你也可以传递一个对象给 assetsPrefix，以指定每种文件类型的不同域名。在这种情况下，fallback属性是必填的，并且它将作为默认值用于任何其他文件。

{
  build: {
    assetsPrefix: {
      'js': 'https://js.cdn.example.com',
      'mjs': 'https://js.cdn.example.com',
      'css': 'https://css.cdn.example.com',
      'fallback': 'https://cdn.example.com'
    }
  }
}

build.serverEntry

类型：string
默认值：'entry.mjs'

当构建到 SSR 时，指定服务器入口的文件名。此入口通常取决于你要部署到的主机，并将由你的适配器为你设置。

注意，建议该文件以 .mjs 结尾，这样运行时就能检测到该文件是一个 JavaScript 模块。

{
  build: {
    serverEntry: 'main.mjs'
  }
}

build.redirects

类型： boolean
默认值： true

添加于： astro@2.6.0

指定是否在构建期间将重定向输出到 HTML 中。

此选项仅适用于 output: 'static' 模式；在 SSR 中，重定向会被作为和其他响应一样对待。

此选项主要适用于具有用于重定向的特殊配置文件且不需要（或不希望）基于 HTML 的重定向的适配器。

{
  build: {
    redirects: false
  }
}

build.inlineStylesheets

类型： 'always' | 'auto' | 'never'
默认值： auto

添加于： astro@2.6.0

控制项目样式是否以单独的 CSS 文件发送到浏览器还是内联到 <style> 标签中。可以从以下选项中进行选择：

'always' - 项目样式都内联到 <style> 标签中。
'auto' - 只有小于 ViteConfig.build.assetsInlineLimit（默认为 4kb）的样式表才会被内联。否则，项目样式将以外部样式表的形式发送。
'never' - 项目样式都以外部样式表的形式发送。

{
  build: {
    inlineStylesheets: `never`,
  },
}

服务器选项

定制 Astro 开发服务器，适用于 astro dev 和 astro preview。

{
  server: { port: 1234, host: true}
}

要根据运行的命令（dev、preview）设置不同的配置，也可以向这个配置选项传递函数。

{
  // 示例：使用函数语法，根据命令进行定制
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 })
}

server.host

类型：string | boolean
默认值：false

添加于： astro@0.24.0

设置服务器应该监听哪些网络 IP 地址（即非本地主机 IP）。

false- 不在网络 IP 地址上公开
true- 侦听所有地址，包括 LAN 和公开地址
[custom-address] - 在 [custom-address] 网络 IP 地址上公开（例如：192.168.0.1）。

server.port

类型：number
默认值：4321

设置服务器监听端口。

如果给定的端口已经在使用，Astro 会自动尝试下一个可用的端口。

{
  server: { port: 8080 }
}

server.open

类型： string | boolean
默认值： false

添加于： astro@4.1.0

控制开发服务器是否应该在启动时在你的浏览器窗口中打开。

传递一个完整的 URL 字符串（例如：”http://example.com” ）或一个路径（例如：“/about”）来指定要打开的 URL。

{
  server: { open: "/about" }
}

server.headers

类型：OutgoingHttpHeaders
默认值：{}

添加于： astro@1.7.0

设置要在 astro dev 和 astro preview 中发送的自定义 HTTP 响应标头。

开发工具栏选项

devToolbar.enabled

类型： boolean
默认值： true

是否启用 Astro 开发者工具栏。这个工具栏使你可以检查你的页面群岛、查看有用的性能和无障碍审计以及其他内容。

这个选项对整个项目生效，要只为你自己禁用工具栏，运行 npm run astro preferences disable devToolbar。要为你的所有项目禁用工具栏，运行 npm run astro preferences disable devToolbar --global。

Prefetch 选项

类型： boolean | object

在你的网站上为链接启用预获取，以提供更快的页面视图过渡效果。（在使用 <ViewTransitions /> 路由器的页面上默认启用。设置 prefetch: false 可以选择退出此行为。）

此配置自动将预获取脚本添加到项目中的每个页面上，让你可以访问 data-astro-prefetch 属性。将此属性添加到页面上的任何 <a /> 链接，以启用该页面的预获取。

<a href="/about" data-astro-prefetch>about</a>

使用 prefetch.defaultStrategy 和 prefetch.prefetchAll 选项进一步自定义默认的预获取行为。

查看预获取指南获取更多信息。

prefetch.prefetchAll

类型： boolean

为所有链接启用预获取，包括那些没有 data-astro-prefetch 属性的链接。当使用 <ViewTransitions /> 路由器时，此值默认为 true。否则，默认值为 false。

prefetch: {
  prefetchAll: true
}

当设置为 true 时，你可以通过在任何单独的链接上设置 data-astro-prefetch="false" 来单独禁用预获取。

<a href="/about" data-astro-prefetch="false">About</a>

prefetch.defaultStrategy

类型： 'tap' | 'hover' | 'viewport' | 'load'
默认值： 'hover'

当链接上设置了 data-astro-prefetch 属性但没有值时，使用的默认预获取策略。

'tap'：在你点击链接之前进行预获取。
'hover'：当你悬停或聚焦在链接上时进行预获取。（默认）
'viewport'：当链接进入视口时进行预获取。
'load'：当页面加载后预获取当前页面的所有链接。

你可以通过在属性上设置值来覆盖此默认值，并为任何单独的链接选择不同的策略。

<a href="/about" data-astro-prefetch="viewport">About</a>

Image 选项

image.endpoint

类型： string
默认值： undefined

添加于： astro@3.1.0

设置在开发和 SSR 中用于图像优化的端点。设置为 undefined 则使用默认端点。

端点将始终注入到 /_image。

{
  image: {
    // 示例：使用自定义图像端点
    endpoint: './src/image-endpoint.ts',
  },
}

image.service

类型：Object
默认值：{entrypoint: 'astro/assets/services/sharp', config?: {}}

添加于： astro@2.1.0

设置用于 Astro 资源支持的图像服务。

该值应该是一个对象，其中包含图像服务应使用的入口点，并可选择地包含一个配置对象，用于传递给该服务。

服务的入口点可以是涵盖的服务之一，也可以是第三方包。

{
  image: {
    // 示例：通过自定义配置启用基于 Sharp 的图像服务
    service: {
       entrypoint: 'astro/assets/services/sharp',
       config: {
         limitInputPixels: false,
      },
     },
  },
}

image.service.config.limitInputPixels

类型： number | boolean
默认值： true

添加于： astro@4.1.0

是否限制 Sharp 图像服务处理的图像大小。

设置为 false 来绕过 Sharp 图像服务的默认图像大小限制，以处理大图像。

image.domains

类型： Array.<string>
默认值： {domains: []}

添加于： astro@2.10.10

定义了一个允许进行远程图像优化的图像源域名列表。Astro 不会对其他远程图像进行优化。

该选项需要一个由域名字符串组成的数组，但不允许使用通配符。或者你也可以使用 image.remotePatterns 来定义一组允许的源 URL 模式。

{
  image: {
    // 示例：允许来自单个域名的远程图像优化。
    domains: ['astro.build'],
  },
}

image.remotePatterns

类型： Array.<RemotePattern>
默认值： {remotePatterns: []}

添加于： astro@2.10.10

定义了允许进行远程图像优化的图像源 URL 模式列表。

remotePatterns 可以通过以下四个属性进行配置：

protocol
hostname
port
pathname

{
  image: {
    // 示例：允许处理所有来自 aws s3 存储桶的图像
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}

你可以使用通配符来定义允许的 hostname 和 pathname 值，正如下所述一样。否则，只有提供的具体值将被配置：

hostname:
- 以 ’**.’ 开头允许所有子域名 (‘endsWith’)。
- 以 ’*.’ 开头只允许一级子域名。
pathname:
- 以 ’/**’ 结尾允许所有子路由 (‘startsWith’)。
- 以 ’/*’ 结尾只允许一级子路由。

Markdown 选项

markdown.shikiConfig

类型：Partial<ShikiConfig>

Shiki 配置选项。使用方法见 markdown 配置文档。

markdown.syntaxHighlight

类型：'shiki' | 'prism' | false
默认值：shiki

可供使用的语法高亮器：

shiki - 使用 Shiki 高亮器
prism - 使用 Prism 高亮器
false - 不使用语法高亮。

{
  markdown: {
    // 示例：在 Markdown 中使用 prism 进行语法高亮显示
    syntaxHighlight: 'prism',
  }
}

markdown.remarkPlugins

类型：RemarkPlugins

通过自定义 Remark 插件来定制 Markdown 构建方式。你可以导入并应用插件函数（推荐），或传递一个值为插件名的字符串。

import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [remarkToc]
  }
}

markdown.rehypePlugins

类型：RehypePlugins

通过自定义 Rehype 插件插件来定制对你的 Markdown 输出内容的处理方式。你可以导入并应用插件函数（推荐），或传递一个值为插件名的字符串。

import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}

markdown.gfm

类型：boolean
默认值：true

添加于： astro@2.0.0

Astro 默认使用 GitHub-flavored Markdown。如果要禁用它，请将gfm标志设置为 false:

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

类型：boolean
默认值：true

添加于： astro@2.0.0

Astro 默认使用 SmartyPants formatter。如果要禁用它，请将smartypants标志设置为 false:

{
  markdown: {
    smartypants: false,
  }
}

markdown.remarkRehype

类型：RemarkRehype

向 remark-rehype 传递选项。

{
  markdown: {
    // 示例：将脚注文本翻译成另一种语言，这里是默认的英文内容
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1"},
  },
};

i18n

类型： object

添加于： astro@3.5.0

配置 i18n 路由，并允许你指定一些自定义选项。

查看我们的指南以获取更多关于 Astro 的国际化的信息。

i18n.defaultLocale

类型： string

添加于： astro@3.5.0

你的网站（或应用）的默认语言环境。这是一个必填字段。

我们并未强制要求使用特定的语言格式或语法，但为了最大程度的兼容性，我们建议在需要的时候使用小写字母和连字符（例如 “es”、“pt-br”）。

i18n.locales

类型： Locales

添加于： astro@3.5.0

网站所支持的包含 defaultLocale 在内所有语言环境的列表。这是一个必填字段。

语言可以列为单独的代码（例如 ['en', 'es', 'pt-br']）或映射到同一个 path 的多个代码（例如 { path: "english", codes: ["en", "en-US"]}）。这些代码将用于确定你部署的网站的 URL 结构。

没有强制执行特定的语言格式或语法，但你的文件夹结构必须与列表中的语言环境完全匹配。当多个 codes 指向同一个自定义的 URL 路径前缀时，将你的内容文件存储在与配置的 path 相同的文件夹中。

i18n.fallback

类型： Record.<string, string>

添加于： astro@3.5.0

当导航到不存在的页面时（例如，尚未创建翻译页面）的回退策略。

使用这个对象为你支持的每种语言声明一个回退的 locale 路由。如果没有指定回退，那么无法访问的页面将返回 404。

示例

以下示例配置你的内容回退策略，将 /pt-br/ 中无法访问的页面重定向到它们的 es 版本，将 /fr/ 中无法访问的页面重定向到它们的 en 版本。无法访问的 /es/ 页面将返回 404。

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    fallback: {
      pt: "es",
      fr: "en"
    }
  }
})

i18n.routing

类型： Routing

添加于： astro@3.7.0

控制路由策略以确定你的网站 URL。请根据你的默认语言的文件夹（或 URL）路径配置来进行设置。

i18n.routing.prefixDefaultLocale

类型： boolean
默认值： false

添加于： astro@3.7.0

当设为 false 时，只有非默认语言的 URL 才会显示语言前缀。 defaultLocale 不会显示语言前缀，内容文件也不会存在于本地化的文件夹中。非默认语言的 URL 会类似于 example.com/[locale]/content/，而默认语言的 URL 则是 example.com/content/。

当设为 true 时，所有 URL 都会显示语言前缀。包括默认语言在内所有的 URL 都会是 example.com/[locale]/content/。包括默认语言的所有语言都会使用本地化的文件夹。

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    routing: {
      prefixDefaultLocale: true,
    }
  }
})

i18n.routing.redirectToDefaultLocale

类型： boolean
默认值： true

添加于： astro@4.2.0

可以用来配置由 src/pages/index.astro 生成的主页 URL (/) 是否在设置 prefixDefaultLocale: true 时重定向到 /[defaultLocale]。

设置 redirectToDefaultLocale: false 可以在你的网站根目录禁用这个自动重定向：

export default defineConfig({
  i18n:{
    defaultLocale: "en",
    locales: ["en", "fr"],
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false
    }
  }
})

i18n.routing.manual

类型： string

添加于： astro@4.6.0

当启用此选项时，Astro 将禁用其 i18n 中间件，以便你可以实现自己的自定义逻辑。在 routing: "manual" 配置下，不能配置其他 routing 选项（例如 prefixDefaultLocale）。

你将负责编写自己的路由逻辑，或者手动执行 Astro 的 i18n 中间件以及你自己的逻辑。

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    routing: {
      prefixDefaultLocale: true,
    }
  }
})

Legacy 标志

为了帮助一些用户在 Astro 不同版本之间进行迁移，我们偶尔会引入 legacy 标志。这些标志允许你在最新的版本中选择使用 Astro 的一些废弃的或其他过时的行为，这样你就可以继续升级并使用新的 Astro 版本。

Experimental 标志

Astro 提供了实验性标志，以便用户提前使用新功能。这些标志不保证稳定。

experimental.directRenderScript

类型： boolean
默认值： false

添加于： astro@4.5.0

启用一种更可靠的策略，以防止在不使用的页面中执行脚本。

脚本将直接按照在 Astro 文件中声明的方式渲染（包括现有的特性，如 TypeScript，导入 node_modules，以及脚本去重）。现在，你也可以在你的 Astro 文件中有条件地渲染脚本。然而，这意味着脚本不再提升到 <head> 中，且页面上的多个脚本不再被打包在一起。如果你启用了这个选项，你应该检查所有的 <script> 标签是否按预期行为。

这个选项将在 Astro 5.0 中默认启用。

{
  experimental: {
    directRenderScript: true,
  },
}

experimental.contentCollectionCache

类型： boolean
默认值： false

添加于： astro@3.5.0

在静态模式下构建时，启用内容集合的持久性缓存。

{
  experimental: {
    contentCollectionCache: true,
  },
}

experimental.contentCollectionJsonSchema

类型： boolean
默认值： false

添加于： astro@4.5.0

此功能将为 type: 'data' 的内容集合自动生成一个 JSON 模式，该模式可用作 VSCode 等工具中 TypeScript 风格的自动完成/提示的 $schema 值。

要启用此功能，请添加实验性标志：

import { defineConfig } from 'astro/config';
export default defineConfig({
  experimental: {
    contentCollectionJsonSchema: true
  }
});

此实验性实现要求你在内容集合的每个数据条目文件中手动引用模式：

{
  "$schema": "../../../.astro/collections/test.schema.json",
  "test": "test"
}

或者，你也可以在你的 VSCode json.schemas 设置中进行配置：

"json.schemas": [
  {
    "fileMatch": [
      "/src/content/test/**"
    ],
    "url": "./.astro/collections/test.schema.json"
  }
]

请注意，这个初始实现使用了一个库，该库对于高级 Zod 模式有已知的问题，因此在启用实验性标志之前，你可能希望查阅这些限制。

experimental.clientPrerender

类型： boolean
默认值： false

添加于： astro@4.2.0

允许在支持的浏览器中启用客户端预渲染来预获取页面。

此功能使用实验性的推测规则 Web API，并全局增强默认的 prefetch 行为，以在客户端预渲染链接。在启用此功能之前，你可能希望查看在客户端预渲染时可能的风险。

在你的 astro.config.mjs 中启用客户端预渲染，以及任何所需的 prefetch 配置选项：

{
  prefetch: {
    prefetchAll: true,
    defaultStrategy: 'viewport',
  },
  experimental: {
    clientPrerender: true,
  },
}

继续在你网站上的任何 <a /> 链接上使用 data-astro-prefetch 属性来使用预获取。不要将 <link> 标签添加到文档的头部或使用 JavaScript 获取页面，而是添加一个带有相应推测规则的 <script> 标签。

客户端预渲染需要浏览器支持。如果不支持 推测规则 API(Speculation Rules API)，prefetch 将回退到支持的策略。

查看预获取指南以获取更多 prefetch 选项和使用方法。

experimental.actions

类型： boolean
默认值： false

添加于： astro@4.8.0 新

Actions 可以帮助你编写可从任何地方调用的类型安全的后端函数。使用 output 属性启用服务端渲染并在 experimental 对象中添加 actions 标志：

{
  output: 'hybrid', // 或 'server'
  experimental: {
    actions: true,
  },
}

在 src/actions/index.ts 中声明所有的操作。这个文件是全局操作处理器。

使用 astro:actions 模块中的 defineAction() 工具定义一个 action。它们接受 handler 属性来定义你的服务端请求处理器。如果你的 action 接受参数，使用 input 属性通过 Zod 对参数进行校验。

此示例定义了两个 action：like 和 comment。like 接受一个包含 postId 字符串的 JSON 对象，而 comment 接受包含 postId、author 和 body 字符串的 FormData。每个 handler 更新你的数据库并返回一个类型安全的响应。

import { defineAction, z } from "astro:actions";

export const server = {
  like: defineAction({
    input: z.object({ postId: z.string() }),
    handler: async ({ postId }, context) => {
      // 更新数据库中的点赞

      return likes;
    },
  }),
  comment: defineAction({
     accept: 'form',
    input: z.object({
      postId: z.string(),
      author: z.string(),
      body: z.string(),
    }),
    handler: async ({ postId }, context) => {
      // 在数据库中插入评论

      return comment;
    },
  }),
};

然后，使用来自 astro:actions 的 actions 对象从你的客户端组件调用一个 action。当使用 JSON 时，你可以传递一个类型安全的对象，或者当在你的 action 定义中使用 accept: 'form' 时，传递一个 FormData 对象：

import { actions } from "astro:actions";
import { useState } from "preact/hooks";

export function Like({ postId }: { postId: string }) {
  const [likes, setLikes] = useState(0);
  return (
    <button
      onClick={async () => {
        const newLikes = await actions.like({ postId });
        setLikes(newLikes);
      }}
    >
      {likes} likes
    </button>
  );
}

export function Comment({ postId }: { postId: string }) {
  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault();
        const formData = new FormData(e.target);
        const result = await actions.blog.comment(formData);
        // 处理结果
      }}
    >
      <input type="hidden" name="postId" value={postId} />
      <label for="author">Author</label>
      <input id="author" type="text" name="author" />
      <textarea rows={10} name="body"></textarea>
      <button type="submit">Post</button>
    </form>
  );
}

要全面了解并对这个实验性 API 提供反馈，请查看 Actions RFC。

experimental.globalRoutePriority

类型： boolean
默认值： false

添加于： astro@4.2.0

将重定向和注入路由与基于文件的项目路由进行同等优先级处理，所有路由都遵循相同的路由优先级顺序规则。

这允许你在项目中对路由有更多的控制，不会自动优先处理某些类型的路由，并且标准化所有路由的路由优先级顺序。

以下示例显示了当如下所示组合文件基础路由、注入路由和重定向时，哪个路由将构建特定页面的 URL：

文件基础路由：/blog/post/[pid]
文件基础路由：/[page]
注入路由：/blog/[...slug]
重定向：/blog/tags/[tag] -> /[tag]
重定向：/posts -> /blog

启用 experimental.globalRoutingPriority（而不是 Astro 4.0 默认的路由优先级顺序）：

/blog/tags/astro 由重定向到 /tags/[tag] 构建（而不是注入路由 /blog/[...slug]）
/blog/post/0 由文件基础路由 /blog/post/[pid] 构建（而不是注入路由 /blog/[...slug]）
/posts 由重定向到 /blog 构建（而不是文件基础路由 /[page]）

在路由冲突的情况下，两个具有相同路由优先级的路由试图构建相同的 URL，Astro 将记录警告，标识出冲突的路由。

experimental.i18nDomains

类型： boolean
默认值： false

添加于： astro@4.3.0

启用域名支持，用于实验性的 domains 路由策略，它允许你配置一个或多个支持的语言的 URL 模式，以使用自定义域名（或子域名）。

当一个语言环境映射到一个域名时，将不会使用 /[locale]/ 路径前缀。然而，src/pages/ 中的本地化文件夹仍然是必需的，包括你配置的 defaultLocale。

其他未配置的语言环境将默认为根据你的 prefixDefaultLocale 策略进行本地化的路径 URL（例如 https://example.com/[locale]/blog）。

export default defineConfig({
  site: "https://example.com",
  output: "server", // 不需要预渲染的页面
  adapter: node({
    mode: 'standalone',
  }),
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    prefixDefaultLocale: false,
    domains: {
      fr: "https://fr.example.com",
      es: "https://example.es",
    },
  },
  experimental: {
    i18nDomains: true,
  },
});

由 astro:i18n 辅助函数 getAbsoluteLocaleUrl() 和 getAbsoluteLocaleUrlList() 构建的页面路由和返回的 URL 将采用在 i18n.domains 中设置的选项。

查看国际化指南以获取更多细节，包括这个实验性功能的限制。

experimental.security

类型： boolean
默认值： false

添加于： astro@4.6.0

为 Astro 网站启用 CSRF 保护。

CSRF 保护仅适用于按需渲染（服务端渲染）的页面，使用 server 或 hybrid 模式。在 hybrid 模式中，页面必须选择退出预渲染。

export default defineConfig({
  output: "server",
  experimental: {
    security: {
      csrfProtection: {
        origin: true
      }
    }
  }
})

experimental.rewriting

类型： boolean
默认值： false

添加于： astro@4.8.0 新

启用一个路由功能，用于在 Astro 页面、端点和 Astro 中间件中重写请求，使你可以对路由进行编程控制。

{
  experimental: {
    rewriting: true,
  },
}

在你的 .astro 文件中使用 Astro.rewrite 来重定向到不同的页面：

---
if (!Astro.props.allowed) {
  return Astro.rewrite("/")
}
---

在你的端点文件中使用 context.rewrite 来重定向到不同的页面：

export function GET(ctx) {
  if (!ctx.locals.allowed) {
    return ctx.rewrite("/")
  }
}

在你的中间件文件中使用 next("/") 来重定向到不同的页面，然后调用下一个中间件函数：

export function onRequest(ctx, next) {
  if (!ctx.cookies.get("allowed")) {
    return next("/") // new signature
  }
  return next();
}

要全面了解并对这个实验性 API 提供反馈，请查看 Rerouting RFC。