配置参考
下面的参考资料涵盖了 Astro 所有支持的配置选项。要了解更多关于配置 Astro 的信息,请阅读我们的配置 Astro 指南。
顶层选项
段落标题 顶层选项site
段落标题 site类型:string
你最终部署的链接。Astro 会使用这个完整的链接来生成网站地图和最终构建的规范链接。强烈建议你设置这个配置项,以获得 Astro 最佳体验。
base
段落标题 base类型:string
你要部署到的基本路径。Astro 在开发过程中会匹配这个路径名,这样你的开发环境就会尽可能地与你的构建环境匹配。
在下面的例子中,astro dev
会在 /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
:
在下面的示例中,在处理时 import.meta.env.BASE_URL
和 config.base
的值都将是 /docs/
:
trailingSlash
段落标题 trailingSlash类型:'always' | 'never' | 'ignore'
默认值:'ignore'
设置开发服务器的路由匹配行为。从以下选项中选择:
'always'
- 只匹配包含尾部斜线的链接(例如:/foo/
)。'never'
- 不匹配包含尾部斜线的链接(例如:/foo
)。'ignore'
- 匹配链接,不管是否存在尾部的/
。
如果你的生产主机对尾部斜杠的工作或不工作有严格的处理方式,请使用该配置选项。
如果你希望自己更严格一些,那么你也可以设置这个选项,这样在开发过程中,无论是否有尾部斜杠的 URL 都不会工作。
另见:
- build.format
redirects
段落标题 redirects类型: Record.<string, RedirectConfig>
默认值: {}
astro@2.9.0
指定重定向的映射关系。其中键为要匹配的路由,值为重定向的路径。
你可以重定向静态和动态路由,但只能重定向到相同类型的路由。例如,你不能有一个 '/article': '/blog/[...slug]'
的重定向。
对于未安装适配器的静态生成站点,这将生成一个使用 <meta http-equiv="refresh">
标签 的客户端重定向,并且不支持状态码。
而使用 SSR 或以 output: static
模式使用静态适配器时,则支持状态码。
默认情况下,Astro 将以 301
的状态对重定向的 GET 请求进行处理,并对其他请求方法使用 308
的状态。
你可以使用重定向配置中的对象自定义 重定向状态码:
output
段落标题 output类型:'static' | 'server' | 'hybrid'
默认值:'static'
指定构建的输出目标。
static
- 构建静态网站,部署到任何静态托管服务器上。server
- 构建应用,部署到支持 SSR(服务器端渲染)的托管服务器上。hybrid
- 构建包含少量服务端渲染页面的静态网站。
另见:
- adapter
adapter
段落标题 adapter类型:AstroIntegration
使用构建适配器将其部署到你最喜爱的服务器、无服务器或边缘主机。导入我们的第一方适配器 Netlify、Vercel,以及更多的适配器来使用 Astro SSR。
有关 SSR 的更多信息,请参见我们的服务器端渲染指南,以及我们的部署指南以获得完整的主机列表。
另见:
- output
integrations
段落标题 integrations类型: AstroIntegration[]
用自定义集成来扩展 Astro 功能。你可以用集成来添加框架支持(如 Solid.js)、新功能(如站点地图)和新库支持(如 Partytown)。
请阅读我们的集成指南,以帮助开始使用 Astro 集成。
root
段落标题 root类型:string
CLI:--root
默认值:"."
(当前工作文件夹)
只有当你在项目根目录以外的目录下运行 astro
CLI 命令时,你才应该提供该选项。通常,这个选项是通过 CLI 而不是 Astro 配置文件提供的,因为 Astro 需要知道项目根目录才能找到配置文件。
如果提供相对路径(例如:--root: './my-project'
),Astro 会根据你当前的工作目录进行解析。
示例
段落标题 示例srcDir
段落标题 srcDir类型:string
默认值:"./src"
设置 Astro 将读取网站的目录。
这个值可以是绝对路径,也可以是相对路径。
publicDir
段落标题 publicDir类型:string
默认值:"./public"
设置静态资源目录。这个目录下的文件在开发过程中被提供给 /
,在构建过程中被复制到构建目录。这些文件总是按原样提供或复制的,没有转换或捆绑。
这个值可以是绝对路径,也可以是相对路径。
outDir
段落标题 outDir类型:string
默认值:"./dist"
设置 astro build
将你的最终构建写入的目录。
这个值可以是绝对路径,也可以是相对路径。
另见:
- build.server
cacheDir
段落标题 cacheDir类型: string
默认值: "./node_modules/.astro"
设置用于缓存构建产物的目录。该目录中的文件将在后续构建中使用,以加快构建时间。
这个值可以是绝对路径,也可以是相对路径。
compressHTML
段落标题 compressHTML类型: boolean
默认值: true
这是一个用于缩小 HTML 输出并减少 HTML 文件大小的选项。
默认情况下,Astro 会从 .astro
组件中,通过无损的方式来移除空格,当然也包括换行符。
为了满足对 HTML 的视觉化渲染,有些空格可能会因此而被保留。这个优化会在开发模式和最终构建中生效。
要禁用 HTML 压缩,请将 compressHTML
标志设置为 false
。
scopedStyleStrategy
段落标题 scopedStyleStrategy类型: 'where' | 'class' | 'attribute'
默认值: 'attribute'
astro@2.4
指定 Astro 组件内部样式作用范围。可选项包括:
'where'
- 使用:where
选择器,不会增加特异性。'class'
- 使用基于类的选择器,会增加 +1 的特异性。'attribute'
- 使用data-
属性,不会增加特异性。
使用 'class'
可以确保 Astro 组件内的元素选择器覆盖全局样式默认值(例如来自全局样式表)。
使用 'where'
可以更好地控制特异性,但需要使用更高特异性的选择器、层级和其他工具来控制应用的选择器。
使用 'attribute'
在你操作元素的 class
属性时很有用,这样你就可以避免你自己的样式逻辑和 Astro 的样式应用之间的冲突。
security
段落标题 security类型: object
默认值: {}
astro@4.9.0
为 Astro 网站启用安全措施。
这些功能仅存在于使用 server
模式按需渲染的页面,或在 hybrid
模式中选择不进行预渲染的页面。
security.checkOrigin
段落标题 security.checkOrigin类型: boolean
默认值: false
astro@4.9.0
启用后,将检查所有现代浏览器自动传递的 “origin” 头是否与每个 Request
发送的 URL 匹配。这用于提供跨站请求伪造(CSRF)保护。
“origin” 检查仅对按需渲染的页面执行,并且仅对具有以下 content-type
头的 POST
、PATCH
、DELETE
和 PUT
请求执行:'application/x-www-form-urlencoded'
、'multipart/form-data'
、'text/plain'
。
如果 “origin” 头与请求的 pathname
不匹配,Astro 将返回 403 状态码,并不会渲染该页面。
vite
段落标题 vite类型: ViteUserConfig
传递额外的配置选项给 Vite。适用于需要使用一些 Astro 不支持的高级配置。
在 vite.dev 上查看完整的 vite
配置对象文档。
示例
段落标题 示例构建选项
段落标题 构建选项build.format
段落标题 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
)
对 Astro.url 的影响
段落标题 对 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
段落标题 build.client类型:string
默认值:'./dist/client'
仅当设置output: 'server'
或 output: 'hybrid'
时,控制你的客户端 CSS 和 JavaScript 的输出文件夹。
outDir
控制代码的构建位置。
这个值是相对于 outDir
的。
build.server
段落标题 build.server类型:string
默认值:'./dist/server'
当构建为 SSR 时控制服务器 JavaScript 的输出目录。
这个值是相对于 outDir
的。
build.assets
段落标题 build.assets类型:string
默认值:'_astro'
astro@2.0.0
指定 Astro 生成的资源(例如打包的 JS 和 CSS)在构建输出中的目录。
另见:
- outDir
build.assetsPrefix
段落标题 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
配置如何):
新增于: astro@4.5.0
你也可以传递一个对象给 assetsPrefix
,以指定每种文件类型的不同域名。
在这种情况下,fallback
属性是必填的,并且它将作为默认值用于任何其他文件。
build.serverEntry
段落标题 build.serverEntry类型:string
默认值:'entry.mjs'
当构建到 SSR 时,指定服务器入口的文件名。此入口通常取决于你要部署到的主机,并将由你的适配器为你设置。
注意,建议该文件以 .mjs
结尾,这样运行时就能检测到该文件是一个 JavaScript 模块。
build.redirects
段落标题 build.redirects类型: boolean
默认值: true
astro@2.6.0
指定是否在构建期间将重定向输出到 HTML 中。此选项仅适用于 output: 'static'
模式;在 SSR 中,重定向会被作为和其他响应一样对待。
此选项主要适用于具有用于重定向的特殊配置文件且不需要(或不希望)基于 HTML 的重定向的适配器。
build.inlineStylesheets
段落标题 build.inlineStylesheets类型: 'always' | 'auto' | 'never'
默认值: auto
astro@2.6.0
控制项目样式是否以单独的 CSS 文件发送到浏览器还是内联到 <style>
标签中。可以从以下选项中进行选择:
'always'
- 项目样式都内联到<style>
标签中。'auto'
- 只有小于ViteConfig.build.assetsInlineLimit
(默认为 4kb)的样式表才会被内联。否则,项目样式将以外部样式表的形式发送。'never'
- 项目样式都以外部样式表的形式发送。
build.concurrency
段落标题 build.concurrency类型: number
默认值: 1
astro@4.16.0
新
并行构建的页面数。
在大多数情况下,你不应更改作为默认值的 1
。
仅当其他减少总体渲染时间的尝试(例如,批处理或缓存长时间运行的任务,如网络请求或数据访问)无法实现或没有帮助时,才使用此选项。 如果该值设置得太高,可能会由于内存资源不足以及 JS 单线程的原因,导致页面渲染变慢。
此功能是稳定的,且不被认定为是实验性功能。但是,此功能仅旨在解决困难的性能问题,并且在 次要版本 中可能会产生破坏性变更,以尽可能保持此选项的性能。如果你正在使用此功能,请检查每个次要版本的 Astro 更新日志。
服务器选项
段落标题 服务器选项定制 Astro 开发服务器,适用于 astro dev
和 astro preview
。
要根据运行的命令(dev
、preview
)设置不同的配置,也可以向这个配置选项传递函数。
server.host
段落标题 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
段落标题 server.port类型:number
默认值:4321
设置服务器监听端口。
如果给定的端口已经在使用,Astro 会自动尝试下一个可用的端口。
server.open
段落标题 server.open类型: string | boolean
默认值: false
astro@4.1.0
控制开发服务器是否应该在启动时在你的浏览器窗口中打开。
传递一个完整的 URL 字符串(例如:”http://example.com” )或一个路径(例如:“/about”)来指定要打开的 URL。
server.headers
段落标题 server.headers类型:OutgoingHttpHeaders
默认值:{}
astro@1.7.0
设置要在 astro dev
和 astro preview
中发送的自定义 HTTP 响应标头。
开发工具栏选项
段落标题 开发工具栏选项devToolbar.enabled
段落标题 devToolbar.enabled类型: boolean
默认值: true
是否启用 Astro 开发者工具栏。这个工具栏使你可以检查你的页面群岛、查看有用的性能和无障碍审计以及其他内容。
这个选项对整个项目生效,要只为你自己禁用工具栏,运行 npm run astro preferences disable devToolbar
。要为你的所有项目禁用工具栏,运行 npm run astro preferences disable devToolbar --global
。
Prefetch 选项
段落标题 Prefetch 选项类型: boolean | object
在你的网站上为链接启用预获取,以提供更快的页面视图过渡效果。(在使用 <ViewTransitions />
路由器的页面上默认启用。设置 prefetch: false
可以选择退出此行为。)
此配置自动将预获取脚本添加到项目中的每个页面上,让你可以访问 data-astro-prefetch
属性。将此属性添加到页面上的任何 <a />
链接,以启用该页面的预获取。
使用 prefetch.defaultStrategy
和 prefetch.prefetchAll
选项进一步自定义默认的预获取行为。
查看 预获取指南 获取更多信息。
prefetch.prefetchAll
段落标题 prefetch.prefetchAll类型: boolean
为所有链接启用预获取,包括那些没有 data-astro-prefetch
属性的链接。当使用 <ViewTransitions />
路由器时,此值默认为 true
。否则,默认值为 false
。
当设置为 true
时,你可以通过在任何单独的链接上设置 data-astro-prefetch="false"
来单独禁用预获取。
prefetch.defaultStrategy
段落标题 prefetch.defaultStrategy类型: 'tap' | 'hover' | 'viewport' | 'load'
默认值: 'hover'
当链接上设置了 data-astro-prefetch
属性但没有值时,使用的默认预获取策略。
'tap'
:在你点击链接之前进行预获取。'hover'
:当你悬停或聚焦在链接上时进行预获取。(默认)'viewport'
:当链接进入视口时进行预获取。'load'
:当页面加载后预获取当前页面的所有链接。
你可以通过在属性上设置值来覆盖此默认值,并为任何单独的链接选择不同的策略。
Image 选项
段落标题 Image 选项image.endpoint
段落标题 image.endpoint类型: string
默认值: undefined
astro@3.1.0
设置在开发和 SSR 中用于图像优化的端点。设置为 undefined
则使用默认端点。
端点将始终注入到 /_image
。
image.service
段落标题 image.service类型:Object
默认值:{entrypoint: 'astro/assets/services/sharp', config?: {}}
astro@2.1.0
设置用于 Astro 资源支持的图像服务。
该值应该是一个对象,其中包含图像服务应使用的入口点,并可选择地包含一个配置对象,用于传递给该服务。
服务的入口点可以是涵盖的服务之一,也可以是第三方包。
image.service.config.limitInputPixels
段落标题 image.service.config.limitInputPixels类型: number | boolean
默认值: true
astro@4.1.0
是否限制 Sharp 图像服务处理的图像大小。
设置为 false
来绕过 Sharp 图像服务的默认图像大小限制,以处理大图像。
image.domains
段落标题 image.domains类型: Array.<string>
默认值: []
astro@2.10.10
定义了一个允许进行远程图像优化的图像源域名列表。Astro 不会对其他远程图像进行优化。
该选项需要一个由域名字符串组成的数组,但不允许使用通配符。或者你也可以使用 image.remotePatterns
来定义一组允许的源 URL 模式。
image.remotePatterns
段落标题 image.remotePatterns类型: Array.<RemotePattern>
默认值: {remotePatterns: []}
astro@2.10.10
定义了允许进行远程图像优化的图像源 URL 模式列表。
remotePatterns
可以通过以下四个属性进行配置:
- protocol
- hostname
- port
- pathname
你可以使用通配符来定义允许的 hostname
和 pathname
值,正如下所述一样。否则,只有提供的具体值将被配置:
-
hostname
:- 以 ’**.’ 开头允许所有子域名 (‘endsWith’)。
- 以 ’*.’ 开头只允许一级子域名。
-
pathname
:- 以 ’/**’ 结尾允许所有子路由 (‘startsWith’)。
- 以 ’/*’ 结尾只允许一级子路由。
Markdown 选项
段落标题 Markdown 选项markdown.shikiConfig
段落标题 markdown.shikiConfig类型:Partial<ShikiConfig>
Shiki 是我们的默认语法高亮器。你可以通过 markdown.shikiConfig
对象配置所有选项:
请参阅 代码语法高亮指南 以获取更多用法和示例。
markdown.syntaxHighlight
段落标题 markdown.syntaxHighlight类型:'shiki' | 'prism' | false
默认值:shiki
配置 Markdown 代码块(```)使用哪种语法高亮器。这决定了 Astro 将应用于你的 Markdown 代码块的 CSS 类。
shiki
- 使用 Shiki 高亮器(默认配置github-dark
主题)prism
- 使用 Prism 高亮器并提供你自己的 Prism 样式表false
- 不使用语法高亮。
markdown.remarkPlugins
段落标题 markdown.remarkPlugins类型:RemarkPlugins
通过自定义 Remark 插件来定制 Markdown 构建方式。你可以导入并应用插件函数(推荐),或传递一个值为插件名的字符串。
markdown.rehypePlugins
段落标题 markdown.rehypePlugins类型:RehypePlugins
通过自定义 Rehype 插件 插件来定制对你的 Markdown 输出内容的处理方式。你可以导入并应用插件函数(推荐),或传递一个值为插件名的字符串。
markdown.gfm
段落标题 markdown.gfm类型:boolean
默认值:true
astro@2.0.0
Astro 默认使用 GitHub-flavored Markdown。如果要禁用它,请将gfm
标志设置为 false
:
markdown.smartypants
段落标题 markdown.smartypants类型:boolean
默认值:true
astro@2.0.0
Astro 默认使用 SmartyPants formatter。如果要禁用它,请将smartypants
标志设置为 false
:
markdown.remarkRehype
段落标题 markdown.remarkRehype类型:RemarkRehype
向 remark-rehype 传递选项。
i18n
段落标题 i18n类型: object
astro@3.5.0
配置 i18n 路由,并允许你指定一些自定义选项。
查看我们的指南以获取更多关于 Astro 的国际化 的信息。
i18n.defaultLocale
段落标题 i18n.defaultLocale类型: string
astro@3.5.0
你的网站(或应用)的默认语言环境。这是一个必填字段。
我们并未强制要求使用特定的语言格式或语法,但为了最大程度的兼容性,我们建议在需要的时候使用小写字母和连字符(例如 “es”、“pt-br”)。
i18n.locales
段落标题 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
段落标题 i18n.fallback类型: Record.<string, string>
astro@3.5.0
当导航到不存在的页面时(例如,尚未创建翻译页面)的回退策略。
使用这个对象为你支持的每种语言声明一个回退的 locale
路由。如果没有指定回退,那么无法访问的页面将返回 404。
示例
段落标题 示例以下示例配置你的内容回退策略,将 /pt-br/
中无法访问的页面重定向到它们的 es
版本,将 /fr/
中无法访问的页面重定向到它们的 en
版本。无法访问的 /es/
页面将返回 404。
i18n.routing
段落标题 i18n.routing类型: 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/
。
包括默认语言的所有语言都会使用本地化的文件夹。
i18n.routing.redirectToDefaultLocale
段落标题 i18n.routing.redirectToDefaultLocale类型: boolean
默认值: true
astro@4.2.0
可以用来配置由 src/pages/index.astro
生成的主页 URL (/
) 是否在设置 prefixDefaultLocale: true
时重定向到 /[defaultLocale]
。
设置 redirectToDefaultLocale: false
可以在你的网站根目录禁用这个自动重定向:
i18n.routing.fallbackType
段落标题 i18n.routing.fallbackType类型:"redirect" | "rewrite"
默认值:"redirect"
astro@4.15.0
当 i18n.fallback
配置为避免给缺失的页面路由显示 404 页面时,此选项用于控制是将用户重定向到回退页面,还是将回退页面的内容重写到原始请求的 URL 上。
默认情况下,Astro 的 i18n 路由会创建页面,将你的访问者重定向到基于你的回退配置的新目的地。浏览器将刷新并在 URL 栏中显示目的地地址。
当 i18n.routing.fallback: "rewrite"
配置时,Astro 则会创建页面,并将回退页面的内容重写到原始请求的 URL 上。
使用以下配置,如果你有 src/pages/en/about.astro
这个文件,但没有 src/pages/fr/about.astro
时,astro build
命令将生成与 dist/en/about.html
页面相同内容的 dist/fr/about.html
页面。
你的网站访问者将在 https://example.com/fr/about/
看到页面的英文版本,而不会被重定向。
i18n.routing.manual
段落标题 i18n.routing.manual类型: string
astro@4.6.0
当启用此选项时,Astro 将禁用其 i18n 中间件,以便你可以实现自己的自定义逻辑。在 routing: "manual"
配置下,不能配置其他 routing
选项(例如 prefixDefaultLocale
)。
你将负责编写自己的路由逻辑,或者手动执行 Astro 的 i18n 中间件以及你自己的逻辑。
Legacy 标志
段落标题 Legacy 标志为了帮助一些用户在 Astro 不同版本之间进行迁移,我们偶尔会引入 legacy
标志。
这些标志允许你在最新的版本中选择使用 Astro 的一些废弃的或其他过时的行为,
这样你就可以继续升级并使用新的 Astro 版本。
Experimental 标志
段落标题 Experimental 标志Astro 提供了实验性标志,以便用户提前使用新功能。这些标志不保证稳定。
experimental.directRenderScript
段落标题 experimental.directRenderScript类型: boolean
默认值: false
astro@4.5.0
启用一种更可靠的策略,以防止在不使用的页面中执行脚本。
脚本将直接按照在 Astro 文件中声明的方式渲染(包括现有的特性,如 TypeScript,导入 node_modules
,以及脚本去重)。现在,你也可以在你的 Astro 文件中有条件地渲染脚本。
然而,这意味着脚本不再提升到 <head>
中,且页面上的多个脚本不再被打包在一起。
如果你启用了这个选项,你应该检查所有的 <script>
标签是否按预期行为。
这个选项将在 Astro 5.0 中默认启用。
experimental.contentCollectionCache
段落标题 experimental.contentCollectionCache类型: boolean
默认值: false
astro@3.5.0
在静态模式下构建时,启用内容集合的持久性缓存。
experimental.clientPrerender
段落标题 experimental.clientPrerender类型: boolean
默认值: false
astro@4.2.0
允许在支持的浏览器中启用客户端预渲染来预获取页面。
此功能使用实验性的 推测规则 Web API,并全局增强默认的 prefetch
行为,以在客户端预渲染链接。
在启用此功能之前,你可能希望查看 在客户端预渲染时可能的风险。
在你的 astro.config.mjs
中启用客户端预渲染,以及任何所需的 prefetch
配置选项:
继续在你网站上的任何 <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 将记录警告,标识出冲突的路由。
experimental.env
段落标题 experimental.env类型: object
默认值: undefined
astro@4.10.0
启用实验性的 astro:env
功能。
astro:env
API 允许你为环境变量配置类型安全的 schema,并指示它们是否应该在服务端或客户端可用。从相应的 /client
或 /server
模块中导入并使用你定义的变量:
要定义环境变量的数据类型和属性,请在你的 Astro 配置中用 experimental.env.schema
声明一个 schema。envField
助手函数允许你将变量定义为字符串、数字或布尔值,并在一个对象中传递属性:
目前支持三种数据类型:字符串、数字和布尔值。
环境变量有三种类型,由 context
(client 或 server)和 access
(secret 或 public)的组合设置在你的 env.schema
中确定:
-
公开客户端变量:这些变量最终会出现在你的客户端和服务端包中,并且可以通过
astro:env/client
模块在客户端和服务端访问: -
公开服务端变量:这些变量最终会出现在你的最终服务端包中,并且可以通过
astro:env/server
模块在服务端访问: -
秘密服务端变量:这些变量不会包含在你的最终包中,可以通过
astro:env/server
模块提供的getSecret()
助手函数在服务端访问。它的实现由你的适配器提供,默认为process.env
:
注意: 因为没有方式可以将数据安全地发送到客户端,所以不支持秘密客户端变量。因此,在你的 schema 中不能同时配置 context: "client"
和 access: "secret"
。
要完整了解此实验性 API 并提供反馈,请查看 Astro Env RFC。
experimental.env.schema
段落标题 experimental.env.schema类型: EnvSchema
默认值: undefined
astro@4.10.0
一个使用 envField
来定义环境变量的数据类型(string
、number
或 boolean
)及其属性的对象:context
(client 或 server)、access
(public 或 secret)、使用的默认值 default
以及该环境变量是否为可选的 optional
(默认为 false
)。
experimental.env.validateSecrets
段落标题 experimental.env.validateSecrets类型: boolean
默认值: false
astro@4.11.6
是否在启动开发服务器或运行构建时验证服务器上的机密。
默认情况下,在启动开发服务器或构建时,服务器上只会验证公有变量,而私有变量只会在运行时被验证。如果启用该功能,启动时也会检查私有变量。这在某些持续集成(CI)管道中非常有用,可以确保在部署前正确设置所有机密。
experimental.serverIslands
段落标题 experimental.serverIslands类型: boolean
默认值: false
astro@4.12.0
启用实验性的服务器群岛功能。 服务器群岛提供了在页面渲染完成后异步延迟渲染组件的功能。
要启用该功能,请使用适配器配置为 在服务器上按需渲染的 output
模式,并在 experimental
对象中添加 serverIslands
标志:
在任意 Astro 组件上使用 server:defer
的指令,来延迟初始化渲染:
外部页面将在构建时(hybrid
)或是在运行时(server
)渲染,它会省去群岛内容,而以 <script>
标签来代替其位置。
页面在浏览器中加载完后,script 标签将通过请求用群岛内容替换掉自己。
任意 Astro 组件都可以被赋予 server:defer
的属性来延迟渲染。没有特殊的 API,你可以像往常一样编写 .astro
代码:
服务器群岛的回退内容
段落标题 服务器群岛的回退内容由于你的组件不会与页面的其他部分一起渲染,因此可能需要添加通用内容(例如:加载中)以临时显示在该位置。这些内容将在页面上群岛加载之前的首次渲染时显示。
使用 slot="fallback"
属性将占位内容添加为 Astro 组件的子组件。当群岛内容可用时,回退内容就会被替换。
下面的示例将一个通用的头像作为回退内容,然后使用视图过渡动画转换为个性化头像:
要全面了解并对这个实验性 API 提供反馈,请查看 服务器群岛 RFC。
experimental.contentIntellisense
段落标题 experimental.contentIntellisense类型: boolean
默认值: false
astro@4.14.0
在兼容的编辑器中,启用此功能将为你的内容集合条目提供 Intellisense 智能提示功能(例如代码补全、快速提示)。
启用后,此功能将生成并添加 JSON 模式到你项目的 .astro
目录中。这些文件可以被 Astro 语言服务器使用,以在内容文件(.md
、.mdx
、.mdoc
)中提供智能提示。
要将此功能与 Astro VS Code 扩展一起使用,你还必须在 VS Code 设置中启用 astro.content-intellisense
选项。对于直接使用 Astro 语言服务器的编辑器,传递 contentIntellisense: true
初始化参数以启用此功能。有关此早期功能的更多详细信息,请参阅 内容智能提示实现的 PR
experimental.contentLayer
段落标题 experimental.contentLayer类型: 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
标志:
使用 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 从单个本地文件中创建多个条目。当你的所有条目都存储在对象数组中时使用。
Loader 不会自动排除以 _
开头的文件。在你的 loader 中使用正则表达式,例如 pattern: '**\/[^_]*.md'
来忽略这些文件。
使用 Content Layer API 查询和渲染
段落标题 使用 Content Layer API 查询和渲染可以使用 与内容集合相同的方式查询集合:
从 Markdown、MDX 或 Markdoc 生成的条目可以直接使用 render()
函数渲染到页面上。
渲染集合条目的语法与当前内容集合的语法不同。
创建 loader
段落标题 创建 loader使用 Content Layer API,你可以构建 loader 来从任何地方加载或生成内容。
例如,你可以创建一个 loader,从远程 API 获取集合条目。
对于更高级的加载逻辑,你可以定义一个 loader 对象。这允许增量更新和条件加载,同时还可以完全访问数据存储。请查看 Content Layer API RFC 中的 API。
迁移现有内容集合以使用 Content Layer API
段落标题 迁移现有内容集合以使用 Content Layer API你可以将一个现有的包含 Markdown、MDX、Markdoc 或 JSON 条目的内容集合转换为使用 Content Layer API。
-
将集合文件夹移出
src/content/
(例如移到src/data/
)。位于src/content/
文件夹中的所有集合将使用现有的内容集合 API。不要移动已存在的
src/content/config.ts
文件。此文件应该包含所有集合的定义,包括使用 Content Layer API 的集合。 -
编辑集合定义。更新后的集合需要一个
loader
,并且 选择集合类型的type
不再可用。 -
将引用从
slug
改成id
。Content layer 集合不需要slug
字段。作为替代,所有集合都使用id
字段。 -
切换到新的
render()
函数。条目本身不再具备render()
方法,因为它们是可序列化的普通对象。 从astro:content
中导入render()
函数替代。
了解更多
段落标题 了解更多要全面了解并 对这个实验性 API 提供反馈,请查看 Content Layer API RFC。
Reference