跳转到内容

配置参考

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

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
// 你的配置在这里...
})

类型string

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

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

类型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_URLconfig.base 的值都将是 /docs

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

在下面的示例中,在处理时 import.meta.env.BASE_URLconfig.base 的值都将是 /docs/

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

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

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

  • 'always' - 只匹配包含尾部斜线的链接(例如:/foo/)。
  • 'never' - 不匹配包含尾部斜线的链接(例如:/foo)。
  • 'ignore'- 匹配链接,不管是否存在尾部的 /

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

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

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

另见

  • build.format

类型: 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',
},
}
}

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

指定构建的输出目标。

  • static- 构建静态网站,部署到任何静态托管服务器上;
  • server - 构建应用,部署到支持 SSR(服务器端渲染)的托管服务器上;
  • hybrid - 构建包含少量服务端渲染页面的静态网站。
import { defineConfig } from 'astro/config';
export default defineConfig({
output: 'static'
})

另见

  • adapter

类型AstroIntegration

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

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

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

另见

  • output

类型: AstroIntegration[]

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

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

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

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

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

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

{
root: './my-project-directory'
}
Terminal window
$ astro build --root ./my-project-directory

类型string
默认值"./src"

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

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

{
srcDir: './www'
}

类型string
默认值"./public"

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

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

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

类型string
默认值"./dist"

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

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

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

另见

  • build.server

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

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

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

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

类型: boolean
默认值: true

这是一个用于缩小 HTML 输出并减少 HTML 文件大小的选项。

默认情况下,Astro 会从 .astro 组件中,通过无损的方式来移除空格,当然也包括换行符。

为了满足对 HTML 的视觉化渲染,有些空格可能会因此而被保留。这个优化会在开发模式和最终构建中生效。

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

{
compressHTML: false
}

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

添加于: astro@2.4

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

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

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

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

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

类型: boolean
默认值: {}

添加于: astro@4.9.0

为 Astro 网站启用安全措施。

这些功能仅存在于使用 server 模式按需渲染的页面,或在 hybrid 模式中选择不进行预渲染的页面。

astro.config.mjs
export default defineConfig({
output: "server",
security: {
checkOrigin: true
}
})

类型: boolean
默认值: ‘false’

添加于: astro@4.9.0

启用后,将检查所有现代浏览器自动传递的 “origin” 头是否与每个 Request 发送的 URL 匹配。这用于提供跨站请求伪造(CSRF)保护。

“origin” 检查仅对按需渲染的页面执行,并且仅对具有以下 content-type 头的 POSTPATCHDELETEPUT 请求执行:'application/x-www-form-urlencoded''multipart/form-data''text/plain'

如果 “origin” 头与请求的 pathname 不匹配,Astro 将返回 403 状态码,并不会渲染该页面。

类型: ViteUserConfig

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

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

{
vite: {
ssr: {
// 示例;如果需要的话,可以强制破坏性包跳过 SSR 处理
external: ['broken-npm-package'],
}
}
}
{
vite: {
// 示例:直接在 Astro 项目中添加自定义 Vite 插件
plugins: [myPlugin()],
}
}

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

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

  • 'file':Astro 将为每个路由生成一个 HTML 文件。(例如:src/pages/about.astrosrc/pages/about/index.astro 都会打包成 /about.html 文件)
  • 'directory':Astro 将生成一个目录,其中包含每个页面的嵌套的 index.html 文件。 (例如:src/pages/about.astrosrc/pages/about/index.astro 都会打包成 /about/index.html 文件)
  • 'preserve':Astro 将根据你的源文件夹中的文件生成 HTML 文件。 (例如:src/pages/about.astro 生成 /about.htmlsrc/pages/about/index.astro 生成 /about/index.html)
{
build: {
// 示例:在构建过程中生 成`page.html` 而不是 `page/index.html`。
format: 'file'
}
}

设置 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'

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

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

这个值是相对于 outDir 的。

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

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

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

这个值是相对于 outDir 的。

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

类型string
默认值'_astro'

添加于: astro@2.0.0

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

{
build: {
assets: '_custom'
}
}

另见

  • outDir

类型: 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'
}
}
}

类型string
默认值'entry.mjs'

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

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

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

类型: boolean
默认值: true

添加于: astro@2.6.0

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

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

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

{
build: {
redirects: false
}
}

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

添加于: astro@2.6.0

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

  • 'always' - 项目样式都内联到 <style> 标签中。
  • 'auto' - 只有小于 ViteConfig.build.assetsInlineLimit(默认为 4kb)的样式表才会被内联。否则,项目样式将以外部样式表的形式发送。
  • 'never' - 项目样式都以外部样式表的形式发送。
{
build: {
inlineStylesheets: `never`,
},
}

定制 Astro 开发服务器,适用于 astro devastro preview

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

要根据运行的命令(devpreview)设置不同的配置,也可以向这个配置选项传递函数。

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

类型string | boolean
默认值false

添加于: astro@0.24.0

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

  • false- 不在网络 IP 地址上公开
  • true- 侦听所有地址,包括 LAN 和公开地址
  • [custom-address] - 在 [custom-address] 网络 IP 地址上公开(例如:192.168.0.1)。

类型number
默认值4321

设置服务器监听端口。

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

{
server: { port: 8080 }
}

类型: string | boolean
默认值: false

添加于: astro@4.1.0

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

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

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

类型OutgoingHttpHeaders
默认值{}

添加于: astro@1.7.0

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

类型: boolean
默认值: true

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

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

类型: boolean | object

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

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

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

使用 prefetch.defaultStrategyprefetch.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>

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

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

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

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

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

类型: string
默认值: undefined

添加于: astro@3.1.0

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

端点将始终注入到 /_image

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

类型: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

段落标题 image.service.config.limitInputPixels

类型: number | boolean
默认值: true

添加于: astro@4.1.0

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

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

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

添加于: astro@2.10.10

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

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

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

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

添加于: astro@2.10.10

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

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

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

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

  • hostname:

    • 以 ’**.’ 开头允许所有子域名 (‘endsWith’)。
    • 以 ’*.’ 开头只允许一级子域名。
  • pathname:

    • 以 ’/**’ 结尾允许所有子路由 (‘startsWith’)。
    • 以 ’/*’ 结尾只允许一级子路由。

类型Partial<ShikiConfig>

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

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

可供使用的语法高亮器:

  • shiki - 使用 Shiki 高亮器
  • prism - 使用 Prism 高亮器
  • false - 不使用语法高亮。
{
markdown: {
// 示例:在 Markdown 中使用 prism 进行语法高亮显示
syntaxHighlight: 'prism',
}
}

类型RemarkPlugins

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

import remarkToc from 'remark-toc';
{
markdown: {
remarkPlugins: [ [remarkToc, { heading: "contents"} ] ]
}
}

类型RehypePlugins

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

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

类型boolean
默认值true

添加于: astro@2.0.0

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

{
markdown: {
gfm: false,
}
}

类型boolean
默认值true

添加于: astro@2.0.0

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

{
markdown: {
smartypants: false,
}
}

类型RemarkRehype

remark-rehype 传递选项。

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

类型: object

添加于: astro@3.5.0

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

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

类型: string

添加于: astro@3.5.0

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

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

类型: Locales

添加于: astro@3.5.0

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

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

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

类型: 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"
}
}
})

类型: Routing

添加于: astro@3.7.0

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

i18n.routing.prefixDefaultLocale

段落标题 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

段落标题 i18n.routing.redirectToDefaultLocale

类型: boolean
默认值: true

添加于: astro@4.2.0

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

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

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

类型: 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,
}
}
})

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

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

experimental.directRenderScript

段落标题 experimental.directRenderScript

类型: boolean
默认值: false

添加于: astro@4.5.0

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

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

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

{
experimental: {
directRenderScript: true,
},
}

类型: boolean
默认值: false

添加于: astro@4.8.0

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

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

src/actions/index.ts 中声明所有的 action。这个文件是全局的 action 处理函数。

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

此示例定义了两个 action:likecommentlike 接受一个包含 postId 字符串的 JSON 对象,而 comment 接受包含 postIdauthorbody 字符串的 FormData。每个 handler 更新你的数据库并返回一个类型安全的响应。

src/actions/index.ts
import { defineAction, z } from "astro:actions";
export const server = {
like: defineAction({
input: z.object({ postId: z.string() }),
handler: async ({ postId }) => {
// 更新数据库中的点赞
return likes;
},
}),
comment: defineAction({
accept: 'form',
input: z.object({
postId: z.string(),
author: z.string(),
body: z.string(),
}),
handler: async ({ postId }) => {
// 在数据库中插入评论
return comment;
},
}),
};

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

这个例子展示了如何从 React 组件中调用likecomment action:

src/components/blog.tsx
import { actions } from "astro:actions";
import { useState } from "react";
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 as HTMLFormElement);
const result = await actions.blog.comment(formData);
// 处理结果
}}
>
<input type="hidden" name="postId" value={postId} />
<label htmlFor="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.contentCollectionCache

段落标题 experimental.contentCollectionCache

类型: boolean
默认值: false

添加于: astro@3.5.0

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

{
experimental: {
contentCollectionCache: true,
},
}

experimental.clientPrerender

段落标题 experimental.clientPrerender

类型: boolean
默认值: false

添加于: astro@4.2.0

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

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

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

astro.config.mjs
{
prefetch: {
prefetchAll: true,
defaultStrategy: 'viewport',
},
experimental: {
clientPrerender: true,
},
}

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

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

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

experimental.globalRoutePriority

段落标题 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 将记录警告,标识出冲突的路由。

类型: boolean
默认值: false

添加于: astro@4.8.0

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

{
experimental: {
rewriting: true,
},
}

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

src/pages/dashboard.astro
---
if (!Astro.props.allowed) {
return Astro.rewrite("/")
}
---

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

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

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

src/middleware.js
export function onRequest(ctx, next) {
if (!ctx.cookies.get("allowed")) {
return next("/") // 新签名
}
return next();
}

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

类型: object
默认值: undefined

添加于: astro@4.10.0

启用实验性的 astro:env 功能。

astro:env API 允许你为环境变量配置类型安全的 schema,并指示它们是否应该在服务端或客户端可用。从相应的 /client/server 模块中导入并使用你定义的变量:

---
import { API_URL } from "astro:env/client"
import { API_SECRET_TOKEN } from "astro:env/server"
const data = await fetch(`${API_URL}/users`, {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${API_SECRET_TOKEN}`
},
})
---
<script>
import { API_URL } from "astro:env/client"
fetch(`${API_URL}/ping`)
</script>

要定义环境变量的数据类型和属性,请在你的 Astro 配置中用 experimental.env.schema 声明一个 schema。envField 助手函数允许你将变量定义为字符串、数字或布尔值,并在一个对象中传递属性:

astro.config.mjs
import { defineConfig, envField } from "astro/config"
export default defineConfig({
experimental: {
env: {
schema: {
API_URL: envField.string({ context: "client", access: "public", optional: true }),
PORT: envField.number({ context: "server", access: "public", default: 4321 }),
API_SECRET: envField.string({ context: "server", access: "secret" }),
}
}
}
})

目前支持三种数据类型:字符串、数字和布尔值。

环境变量有三种类型,由 context(client 或 server)和 access(secret 或 public)的组合设置在你的 env.schema 中确定:

  • 公开客户端变量:这些变量最终会出现在你的客户端和服务端包中,并且可以通过 astro:env/client 模块在客户端和服务端访问:

    import { API_URL } from "astro:env/client"
  • 公开服务端变量:这些变量最终会出现在你的最终服务端包中,并且可以通过 astro:env/server 模块在服务端访问:

    import { PORT } from "astro:env/server"
  • 秘密服务端变量:这些变量不会包含在你的最终包中,可以通过 astro:env/server 模块提供的 getSecret() 助手函数在服务端访问。它的实现由你的适配器提供,默认为 process.env

    import { API_SECRET, getSecret } from "astro:env/server"
    const SECRET_NOT_IN_SCHEMA = getSecret("SECRET_NOT_IN_SCHEMA") // string | undefined

注意: 因为没有方式可以将数据安全地发送到客户端,所以不支持秘密客户端变量。因此,在你的 schema 中不能同时配置 context: "client"access: "secret"

要完整了解此实验性 API 并提供反馈,请查看 Astro Env RFC

类型: EnvSchema
默认值: undefined

添加于: astro@4.10.0

一个使用 envField 来定义环境变量的数据类型(stringnumberboolean)及其属性的对象:context(client 或 server)、access(public 或 secret)、使用的默认值 default 以及该环境变量是否为可选的 optional(默认为 false)。

astro.config.mjs
import { defineConfig, envField } from "astro/config"
export default defineConfig({
experimental: {
env: {
schema: {
API_URL: envField.string({ context: "client", access: "public", optional: true }),
PORT: envField.number({ context: "server", access: "public", default: 4321 }),
API_SECRET: envField.string({ context: "server", access: "secret" }),
}
}
}
})

experimental.env.validateSecrets

段落标题 experimental.env.validateSecrets

类型: boolean
默认值: false

添加于: astro@4.11.6

是否在启动开发服务器或运行构建时验证服务器上的机密。

默认情况下,在启动开发服务器或构建时,服务器上只会验证公有变量,而私有变量只会在运行时被验证。如果启用该功能,启动时也会检查私有变量。这在某些持续集成(CI)管道中非常有用,可以确保在部署前正确设置所有机密。

astro.config.mjs
import { defineConfig, envField } from "astro/config"
export default defineConfig({
experimental: {
env: {
schema: {
// ...
},
validateSecrets: true
}
}
})

experimental.serverIslands

段落标题 experimental.serverIslands

类型: boolean
默认值: false

添加于: astro@4.12.0

启用实验性的服务器群岛功能。 服务器群岛提供了在页面渲染完成后异步延迟渲染组件的功能。

要启用该功能,请使用适配器配置为 在服务器上按需渲染的 output 模式,并在 experimental 对象中添加 serverIslands 标志:

{
output: 'hybrid', // 或是 'server'
adapter: nodejs({ mode: 'standalone' }),
experimental: {
serverIslands: true,
},
}

在任意 Astro 组件上使用 server:defer 的指令,来延迟初始化渲染:

---
import Avatar from '~/components/Avatar.astro';
---
<Avatar server:defer />

外部页面将在构建时(hybrid)或是在运行时(server)渲染,它会省去群岛内容,而以 <script> 标签来代替其位置。

页面在浏览器中加载完后,script 标签将通过请求用群岛内容替换掉自己。

任意 Astro 组件都可以被赋予 server:defer 的属性来延迟渲染。没有特殊的 API,你可以像往常一样编写 .astro 代码:

---
import { getUser } from '../api';
const user = await getUser(Astro.locals.userId);
---
<img class="avatar" src={user.imageUrl}>

服务器群岛的回退内容

段落标题 服务器群岛的回退内容

由于你的组件不会与页面的其他部分一起渲染,因此可能需要添加通用内容(例如:加载中)以临时显示在该位置。这些内容将在页面上群岛加载之前的首次渲染时显示。

使用 slot="fallback" 属性将占位内容添加为 Astro 组件的子组件。当群岛内容可用时,回退内容就会被替换。

下面的示例将一个通用的头像作为回退内容,然后使用视图过渡动画转换为个性化头像:

<Avatar server:defer>
<svg slot="fallback" class="generic-avatar" transition:name="avatar">...</svg>
</Avatar>

要全面了解并对这个实验性 API 提供反馈,请查看 服务器群岛 RFC

experimental.contentIntellisense

段落标题 experimental.contentIntellisense

类型: boolean
默认值: false

添加于: astro@4.14.0

在兼容的编辑器中,启用此功能将为你的内容集合条目提供 Intellisense 智能提示功能(例如代码补全、快速提示)。

启用后,此功能将生成并添加 JSON 模式到你项目的 .astro 目录中。这些文件可以被 Astro 语言服务器使用,以在内容文件(.md.mdx.mdoc)中提供智能提示。

{
experimental: {
contentIntellisense: true,
},
}

要将此功能与 Astro VS Code 扩展一起使用,你还必须在 VS Code 设置中启用 astro.content-intellisense 选项。对于直接使用 Astro 语言服务器的编辑器,传递 contentIntellisense: true 初始化参数以启用此功能。

类型: boolean
默认值: false

添加于: astro@4.14.0

Content Layer API 是一种新的处理 Astro 中内容和数据的方式。它类似于 内容集合 并构建在内容集合之上,将其从 src/content/ 中的本地文件扩展到允许你通过为你的集合添加 loader 来从任何地方获取内容,包括远程 API。

只需要一点小改动,你就可以将现有的内容集合 迁移到 Content Layer API。但是,不需要一次性更新所有集合来添加一个由 Content Layer API 提供支持的新集合。你可以在 src/content/config.ts 中同时定义使用现有的和新 API 的集合。

Content Layer API 为更强大和更高性能的网站设计,帮助网站扩展到数千个页面。数据在构建之间进行缓存,并进行增量更新。Markdown 解析速度也提高了 5-10 倍,内存使用量也减少了相似的规模,MDX 的速度也提高了 2-3 倍。

要启用该功能,请在你的 Astro 配置中的 experimental 对象中添加 contentLayer 标志:

astro.config.mjs
{
experimental: {
contentLayer: true,
}
}

使用 loader 请求数据

段落标题 使用 loader 请求数据

Content Layer API 允许你从 src/content/ 文件夹之外(无论是在你的项目中本地存储还是远程存储)获取内容,并使用 loader 属性来检索数据。

loader 在集合的 schema 中定义,并返回一个条目数组。Astro 提供了两个内置的 loader 函数(glob()file())用于获取你的本地内容,以及让你构建自己的 loader 并获取远程数据 的 API。

glob() loader 从文件系统上的任何地方的 Markdown、MDX、Markdoc 或 JSON 文件目录中创建条目。它接受一个匹配条目文件的 pattern,以及你的文件所在的 base 文件路径。当每个条目对于一个文件时使用此选项。

file loader 从单个本地文件中创建多个条目。当你的所有条目都存储在对象数组中时使用。

src/content/config.ts
import { defineCollection, z } from 'astro:content';
import { glob, file } from 'astro/loaders';
const blog = defineCollection({
// 默认情况下,ID 是从相对于
// `base` 的文件路径生成的 slug
loader: glob({ pattern: "**\/*.md", base: "./src/data/blog" }),
schema: z.object({
title: z.string(),
description: z.string(),
pubDate: z.coerce.date(),
updatedDate: z.coerce.date().optional(),
})
});
const dogs = defineCollection({
// 该路径是相对于项目根目录,或者是绝对路径。
loader: file("src/data/dogs.json"),
schema: z.object({
id: z.string(),
breed: z.string(),
temperament: z.array(z.string()),
}),
});
export const collections = { blog, dogs };

使用 Content Layer API 查询和渲染

段落标题 使用 Content Layer API 查询和渲染

可以使用 与内容集合相同的方式查询集合

src/pages/index.astro
import { getCollection, getEntry } from 'astro:content';
// 获取集合中的所有条目。
// 需要集合的名字作为参数。
const allBlogPosts = await getCollection('blog');
// 从集合中获取单个条目。
// 需要集合的名字和条目的 ID 作为参数。
const labradorData = await getEntry('dogs', 'labrador-retriever');

从 Markdown、MDX 或 Markdoc 生成的条目可以直接使用 render() 函数渲染到页面上。

src/pages/[slug].astro
---
import { getEntry, render } from 'astro:content';
const post = await getEntry('blog', Astro.params.slug);
const { Content, headings } = await render(post);
---
<Content />

使用 Content Layer API,你可以构建 loader 来从任何地方加载或生成内容。

例如,你可以创建一个 loader,从远程 API 获取集合条目。

src/content/config.ts
const countries = defineCollection({
loader: async () => {
const response = await fetch("https://restcountries.com/v3.1/all");
const data = await response.json();
// 必须返回具有 id 属性的条目数组,
// 或具有 ID 作为键和条目作为值的对象
return data.map((country) => ({
id: country.cca3,
...country,
}));
},
// 可选择添加 schema
// schema: z.object...
});
export const collections = { countries };

对于更高级的加载逻辑,你可以定义一个 loader 对象。这允许增量更新和条件加载,同时还可以完全访问数据存储。请查看 Content Layer API RFC 中的 API。

迁移现有内容集合以使用 Content Layer API

段落标题 迁移现有内容集合以使用 Content Layer API

你可以将一个现有的包含 Markdown、MDX、Markdoc 或 JSON 条目的内容集合转换为使用 Content Layer API。

  1. 将集合文件夹移出 src/content/ (例如移到 src/data/)。位于 src/content/ 文件夹中的所有集合将使用现有的内容集合 API。

    不要移动已存在的 src/content/config.ts 文件。此文件应该包含所有集合的定义,包括使用 Content Layer API 的集合。

  2. 编辑集合定义。更新后的集合需要一个 loader,并且 选择集合类型的 type不再可用。

    src/content/config.ts
    import { defineCollection, z } from 'astro:content';
    import { glob } from 'astro/loaders';
    const blog = defineCollection({
    // content layer 不需要定义 `type`
    type: 'content',
    loader: glob({ pattern: '**\/[^_]*.md', base: "./src/data/blog" }),
    schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    }),
    });
  3. 将引用从 slug 改成 id。Content layer 集合不需要 slug 字段。作为替代,所有集合都使用 id 字段。

    src/pages/index.astro
    ---
    export async function getStaticPaths() {
    const posts = await getCollection('blog');
    return posts.map((post) => ({
    params: { slug: post.slug },
    params: { slug: post.id },
    props: post,
    }));
    }
    ---
  4. 切换到新的 render() 函数。条目本身不再具备 render() 方法,因为它们是可序列化的普通对象。 从 astro:content 中导入 render() 函数替代。

    src/pages/index.astro
    ---
    import { getEntry } from 'astro:content';
    import { getEntry, render } from 'astro:content';
    const post = await getEntry('blog', params.slug);
    const { Content, headings } = await post.render();
    const { Content, headings } = await render(post);
    ---
    <Content />

要全面了解并 对这个实验性 API 提供反馈,请查看 Content Layer API RFC

贡献

你有什么想法?

社区