配置参考

下面的参考资料涵盖了 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 的视觉化渲染，有些空格可能会因此而被保留。这个优化会在开发模式和最终构建中生效。

要禁用 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 的样式应用之间的冲突。

security

类型： boolean
默认值： {}

添加于： astro@4.9.0

为 Astro 网站启用安全措施。

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

export default defineConfig({
  output: "server",
  security: {
    checkOrigin: true
  }
})

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

类型： 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, { heading: "contents"} ] ]
  }
}

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

类型： 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：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 }) => {
      // 更新数据库中的点赞

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

      return comment;
    },
  }),
};

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

这个例子展示了如何从 React 组件中调用like 和 comment action：

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

类型： boolean
默认值： false

添加于： astro@3.5.0

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

{
  experimental: {
    contentCollectionCache: true,
  },
}

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.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.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("/") // 新签名
  }
  return next();
}

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

experimental.env

类型： 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 助手函数允许你将变量定义为字符串、数字或布尔值，并在一个对象中传递属性：

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。

experimental.env.schema

类型： EnvSchema
默认值： undefined

添加于： astro@4.10.0

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

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

类型： boolean
默认值： false

添加于： astro@4.11.6

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

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

import { defineConfig, envField } from "astro/config"

export default defineConfig({
  experimental: {
    env: {
      schema: {
        // ...
      },
      validateSecrets: true
    }
  }
})

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

类型： 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 初始化参数以启用此功能。

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 标志：

{
  experimental: {
    contentLayer: true,
  }
}

使用 `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 从单个本地文件中创建多个条目。当你的所有条目都存储在对象数组中时使用。

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 查询和渲染

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

import { getCollection, getEntry } from 'astro:content';

// 获取集合中的所有条目。
// 需要集合的名字作为参数。
const allBlogPosts = await getCollection('blog');

// 从集合中获取单个条目。
// 需要集合的名字和条目的 ID 作为参数。
const labradorData = await getEntry('dogs', 'labrador-retriever');

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

---
import { getEntry, render } from 'astro:content';

const post = await getEntry('blog', Astro.params.slug);

const { Content, headings } = await render(post);
---

<Content />

创建 loader

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

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

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

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

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

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

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

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(),
  }),
});

将引用从 slug 改成 id。Content layer 集合不需要 slug 字段。作为替代，所有集合都使用 id 字段。

---
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug },
    params: { slug: post.id },
    props: post,
  }));
}
---

切换到新的 render() 函数。条目本身不再具备 render() 方法，因为它们是可序列化的普通对象。从 astro:content 中导入 render() 函数替代。

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

贡献

社区

配置参考

顶层选项

site

base

trailingSlash

redirects

output

adapter

integrations

root

示例

srcDir

publicDir

outDir

cacheDir

compressHTML

scopedStyleStrategy

security

security.checkOrigin

vite

示例

构建选项

build.format

对 Astro.url 的影响

build.client

build.server

build.assets

build.assetsPrefix

build.serverEntry

build.redirects

build.inlineStylesheets

服务器选项

server.host

server.port

server.open

server.headers

开发工具栏选项

devToolbar.enabled

Prefetch 选项

prefetch.prefetchAll

prefetch.defaultStrategy

Image 选项

image.endpoint

image.service

image.service.config.limitInputPixels

image.domains

image.remotePatterns

Markdown 选项

markdown.shikiConfig

markdown.syntaxHighlight

markdown.remarkPlugins

markdown.rehypePlugins

markdown.gfm

markdown.smartypants

markdown.remarkRehype

i18n

i18n.defaultLocale

i18n.locales

i18n.fallback

示例

i18n.routing

i18n.routing.prefixDefaultLocale

i18n.routing.redirectToDefaultLocale

i18n.routing.manual

Legacy 标志

Experimental 标志

experimental.directRenderScript

experimental.actions

experimental.contentCollectionCache

experimental.clientPrerender

experimental.globalRoutePriority

experimental.rewriting

experimental.env

experimental.env.schema

experimental.env.validateSecrets

experimental.serverIslands

服务器群岛的回退内容

experimental.contentIntellisense

experimental.contentLayer

使用 loader 请求数据

使用 `loader` 请求数据