配置参考

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

import { defineConfig } from 'astro/config'

export default defineConfig({
  // your configuration options here...
})

顶级选项

site

类型： string

你最终部署的 URL。Astro 使用此完整 URL 在最终构建中生成站点地图和规范化 URL。强烈建议设置此配置，以充分利用 Astro。

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

base

类型： string

部署时的基本路径。Astro 将在开发和生产构建中使用此路径作为页面和资源的根目录。

在下面的示例中，astro dev 将在 /docs 启动你的服务器。

{
  base: '/docs'
}

使用此选项时，所有静态资源导入和 URL 都应添加该基本路径作为前缀。你可以通过 import.meta.env.BASE_URL 访问此值。

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

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

此外，在将 config.base 的配置值提供给集成之前，Astro 会在内部对其进行处理。集成读取到的 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'

为开发服务器和按需渲染页面的末尾斜杠设置路由匹配行为。从以下选项中选择：

'ignore' - 无论 URL 是否存在末尾的 “/”，都进行匹配。“/about” 和 “/about/” 的请求都将匹配同一路由。
'always' - 仅匹配包含末尾斜杠的 URL（例如：“/about/”）。在生产环境中，为方便起见，对没有末尾斜杠的按需渲染页面的请求将被重定向到正确的 URL。然而，在开发环境中，它们会显示一个警告页面，提醒你已配置 always。
'never' - 仅匹配不包含末尾斜杠的 URL（例如：“/about”）。在生产环境中，为方便起见，对带有末尾斜杠的按需渲染页面的请求将被重定向到正确的 URL。然而，在开发环境中，它们会显示一个警告页面，提醒你已配置 never。

当在生产环境中对 GET 请求进行重定向时，将使用 301（永久）重定向。对于所有其他请求方法，将使用 308（永久，并保留请求方法）重定向。

预渲染页面上的末尾斜杠由托管平台处理，可能不会遵循你选择的配置。请参阅你的托管平台文档以获取更多信息。目前你不能为此用例使用 Astro 重定向。

{
  // Example: Require a trailing slash during development
  trailingSlash: 'always'
}

另请参阅

build.format

redirects

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

添加于： astro@2.9.0

指定重定向的映射，其中键是要匹配的路由，值是要重定向到的路径。

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

export default defineConfig({
  redirects: {
   '/old': '/new',
   '/blog/[...slug]': '/articles/[...slug]',
   '/about': 'https://example.com/about',
   '/news': {
     status: 302,
     destination: 'https://example.com/news'
   },
   // '/product1/', '/product1' // Note, this is not supported
  }
})

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

当使用 SSR 或在 output: static 模式下使用静态适配器时，支持状态码。Astro 将以 301 状态码处理重定向的 GET 请求，并对任何其他请求方法使用 308 状态码。

你可以在重定向配置中使用一个对象来自定义重定向状态码

export default defineConfig({
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
})

output

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

指定构建的输出目标。

'static' - 默认预渲染所有页面，如果没有任何页面选择退出预渲染，则输出一个完全静态的站点。
'server' - 默认对所有页面使用服务器端渲染（SSR），始终输出一个服务器渲染的站点。

import { defineConfig } from 'astro/config';

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

另请参阅

adapter

adapter

类型： AstroIntegration

使用构建适配器将你的项目部署到你喜欢的服务器、无服务器或边缘主机上。导入我们的一个官方适配器（Cloudflare、Netlify、Node.js、Vercel）或探索社区适配器以在你的 Astro 项目中启用按需渲染。

请参阅我们的按需渲染指南，了解有关 Astro 服务器渲染选项的更多信息。

import netlify from '@astrojs/netlify';
{
  // Example: Build for Netlify serverless deployment
  adapter: netlify(),
}

另请参阅

output

integrations

类型： AstroIntegration[]

使用自定义集成来扩展 Astro。集成是添加框架支持（如 Solid.js）、新功能（如站点地图）和新库（如 Partytown）的一站式解决方案。

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

import react from '@astrojs/react';
import mdx from '@astrojs/mdx';
{
  // Example: Add React + MDX support to Astro
  integrations: [react(), mdx()]
}

root

类型： string
命令行： --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 的视觉渲染效果。这在开发模式和最终构建中都会发生。

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

{
  compressHTML: false
}

scopedStyleStrategy

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

添加于： astro@2.4

指定在 Astro 组件中用于限定样式作用域的策略。从以下选项中选择：

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

当你想确保 Astro 组件中的元素选择器能覆盖全局样式默认值（例如来自全局样式表）时，使用 'class' 会很有帮助。使用 'where' 让你能更好地控制特指性，但需要你使用更高特指性的选择器、层（layers）和其他工具来控制应用哪些选择器。当你在操作元素的 class 属性并且需要避免你自己的样式逻辑与 Astro 应用样式的方式之间发生冲突时，使用 'attribute' 会很有用。

security

类型： Record<"checkOrigin", boolean> | undefined
默认值： {checkOrigin: true}

新增于： astro@4.9.0

为 Astro 网站启用安全措施。

这些功能仅适用于使用 server 模式按需渲染的页面，或在 static 模式下选择退出预渲染的页面。

默认情况下，Astro 会自动检查按需渲染页面中每个请求发送的“origin”标头是否与 URL 匹配。你可以通过将 checkOrigin 设置为 false 来禁用此行为。

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

security.checkOrigin

类型： boolean
默认值： true

新增于： astro@4.9.0

执行一个检查，确保所有现代浏览器自动传递的“origin”标头与每个 Request 发送的 URL 相匹配。这用于提供跨站请求伪造（CSRF）保护。

“origin”检查仅在按需渲染页面时执行，且仅针对 POST、PATCH、DELETE 和 PUT 请求，且 content-type 标头为以下之一：'application/x-www-form-urlencoded'、'multipart/form-data'、'text/plain'。

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

vite

类型： ViteUserConfig

向 Vite 传递额外的配置选项。当 Astro 不支持你可能需要的某些高级配置时，这很有用。

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

示例

{
  vite: {
    ssr: {
      // Example: Force a broken package to skip SSR processing, if needed
      external: ['broken-npm-package'],
    }
  }
}

{
  vite: {
    // Example: Add custom vite plugins directly to your Astro project
    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: {
    // Example: Generate `page.html` instead of `page/index.html` during build.
    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) 创建相对 URL 时，在开发和构建之间你将获得一致的行为。

为了防止在开发中末尾斜杠行为不一致，你可以根据你的构建格式将trailingSlash 选项限制为 'always' 或 'never'。

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

build.client

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

在构建带有服务器渲染页面的网站时，控制客户端 CSS 和 JavaScript 的输出目录。outDir 控制代码构建到的位置。

此值相对于 outDir。

{
  output: 'server',
  build: {
    client: './client'
  }
}

build.server

类型： string
默认值： './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`,
  },
}

build.concurrency

类型： number
默认值： 1

添加于： astro@4.16.0

并行构建的页面数量。

在大多数情况下，你不应更改默认值 1。

仅当其他减少整体渲染时间的尝试（例如，批量或缓存长时间运行的任务，如 fetch 调用或数据访问）不可行或不足时，才使用此选项。如果数字设置得太高，由于内存资源不足以及 JS 是单线程的，页面渲染可能会变慢。

{
  build: {
    concurrency: 2
  }
}

服务器选项

自定义 Astro 开发服务器，供 astro dev 和 astro preview 使用。

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

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

{
  // Example: Use the function syntax to customize based on command
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 })
}

server.host

类型： string | boolean
默认值： false

添加于： astro@0.24.0

设置服务器应监听的网络 IP 地址（即非 localhost IP）。

false - 不在网络 IP 地址上暴露
true - 监听所有地址，包括局域网和公共地址
[custom-address] - 在 [custom-address] 的网络 IP 地址上暴露（例如：192.168.0.1）

server.port

类型： number
默认值： 4321

设置服务器应监听的端口。

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

{
  server: { port: 8080 }
}

server.allowedHosts

类型： Array<string> | true
默认值： []

添加于： astro@5.4.0

Astro 允许响应的主机名列表。当值为 true 时，允许任何主机名。

{
  server: {
    allowedHosts: ['staging.example.com', 'qa.example.com']
  }
}

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 响应头。

会话选项

添加于： astro@5.7.0

为你的 Astro 项目配置会话存储。这用于以持久化的方式存储会话数据，以便可以在不同的请求之间访问。某些适配器可能提供默认的会话驱动程序，但你可以用自己的配置来覆盖它。

有关更多信息，请参阅会话指南。

  {
    session: {
      // The name of the Unstorage driver
      driver: 'redis',
      // The required options depend on the driver
      options: {
        url: process.env.REDIS_URL,
      },
      ttl: 3600, // 1 hour
    }
  }

session.driver

类型： string | undefined

添加于： astro@5.7.0

Node、Cloudflare 和 Netlify 适配器会自动为你配置默认的会话存储驱动程序，但如果你愿意，或者你正在使用的适配器没有提供驱动程序，你可以指定自己的驱动程序。

该值为 Unstorage 驱动程序文档中的“驱动程序名称”。

{
  adapter: vercel(),
  session: {
    driver: "redis",
  },
}

session.options

类型： Record<string, unknown> | undefined
默认值： {}

添加于： astro@5.7.0

用于会话存储的驱动程序特定选项。这些选项取决于你正在使用的驱动程序。有关每个驱动程序可用选项的更多信息，请参阅 Unstorage 文档。

{
   session: {
     driver: "redis",
     options: {
       url: process.env.REDIS_URL
     },
   }
}

session.cookie

类型： string | AstroCookieSetOptions | undefined
默认值： { name: "astro-session", sameSite: "lax", httpOnly: true, secure: true }

添加于： astro@5.7.0

会话 cookie 的配置。如果设置为字符串，它将被用作 cookie 名称。或者，你可以传递一个带有附加选项的对象。这些选项将与默认值合并。

{
 session: {
   // If set to a string, it will be used as the cookie name.
   cookie: "my-session-cookie",
 }
}

{
 session: {
   // If set to an object, it will be used as the cookie options.
   cookie: {
     name: "my-session-cookie",
     sameSite: "lax",
     secure: true,
   }
 }
}

session.ttl

类型： number | undefined
默认值： Infinity

添加于： astro@5.7.0

一个可选的会话值默认生存时间（time-to-live）过期期限，单位为秒。

默认情况下，会话值会一直存在，直到它们被删除或会话被销毁，并且不会因为经过特定时间而自动过期。设置 session.ttl 可以为你的会话值添加一个默认的过期期限。向 session.set() 传递一个 ttl 选项将覆盖该单个条目的全局默认值。

{
 session: {
   // Set a default expiration period of 1 hour (3600 seconds)
   ttl: 3600,
 }
}

devToolbar.enabled

类型： boolean
默认值： true

是否启用 Astro 开发工具栏。此工具栏允许你检查页面岛屿，查看有关性能和可访问性的有用审计等。

此选项适用于整个项目，若只想为自己禁用工具栏，请运行 npm run astro preferences disable devToolbar。要为所有 Astro 项目禁用工具栏，请运行 npm run astro preferences disable devToolbar --global。

预取选项

类型： boolean | object

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

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

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

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

更多信息请参阅预获取指南。

prefetch.prefetchAll

类型： boolean

为所有链接（包括没有 data-astro-prefetch 属性的链接）启用预获取。当使用 <ClientRouter /> 路由器时，此值默认为 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.endpoint

类型： Object
默认值： {route: '/_image', entrypoint: undefined}

添加于： astro@3.1.0

设置在开发和 SSR 中用于图像优化的端点。entrypoint 属性可以设置为 undefined 以使用默认的图像端点。

{
  image: {
    // Example: Use a custom image endpoint at `/custom_endpoint`
    endpoint: {
       route: '/custom_endpoint',
       entrypoint: 'src/my_endpoint.ts',
    },
  },
}

image.service

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

添加于： astro@2.1.0

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

该值应为一个对象，包含要使用的图像服务的入口点，以及可选的、传递给服务的配置对象。

服务入口点可以是内置服务之一，也可以是第三方包。

{
  image: {
    // Example: Enable the Sharp-based image service with a custom config
    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>
默认值： []

添加于： astro@2.10.10

定义一个允许用于远程图像优化的图像源域列表。Astro 不会优化任何其他远程图像。

此选项需要一个由单个域名字符串组成的数组。不允许使用通配符。请改用 image.remotePatterns 来定义允许的源 URL 模式列表。

{
  image: {
    // Example: Allow remote image optimization from a single domain
    domains: ['astro.build'],
  },
}

image.remotePatterns

类型： Array<RemotePattern>
默认值： []

添加于： astro@2.10.10

定义一个允许用于远程图像优化的图像源 URL 模式列表。

remotePatterns 可以配置四个属性

protocol
hostname
port
pathname

{
  image: {
    // Example: allow processing all images from your aws s3 bucket
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}

你可以使用通配符来定义允许的 hostname 和 pathname 值，如下所述。否则，将只配置提供的确切值： hostname

以 ‘**.’ 开头以允许所有子域名（‘endsWith’）。
以 ‘*.’ 开头以仅允许一级子域名。

pathname:

以 ‘/**’ 结尾以允许所有子路由（‘startsWith’）。
以 ‘/*’ 结尾以仅允许一级子路由。

image.responsiveStyles

类型： boolean
默认值： false

添加于： astro@5.10.0

是否自动为响应式图片添加全局样式。除非你正在自己为图片设置样式，否则应该启用此选项。

仅当通过配置或在图片组件上使用 layout 属性将 layout 设置为 constrained、full-width 或 fixed 时，此选项才会被使用。

更多信息请参阅图片文档。

image.layout

类型： ImageLayout
默认值： undefined

添加于： astro@5.10.0

响应式图片的默认布局类型。可通过图片组件上的 layout 属性覆盖。

constrained - 图片将缩放以适应容器，保持其宽高比，但不会超过指定的尺寸。
fixed - 图片将保持其原始尺寸。
full-width - 图片将缩放以适应容器，保持其宽高比。

更多详情请参阅layout 组件属性。

image.objectFit

类型： ImageFit
默认值： "cover"

添加于： astro@5.10.0

响应式图片的 object-fit CSS 属性值。可通过图片组件上的 fit 属性覆盖。需要为 layout 设置一个值。

更多详情请参阅fit 组件属性。

image.objectPosition

类型： string
默认值： "center"

添加于： astro@5.10.0

响应式图片的默认 object-position CSS 属性值。可通过图片组件上的 position 属性覆盖。需要为 layout 设置一个值。

更多详情请参阅position 组件属性。

image.breakpoints

类型： Array<number>
默认值： [640, 750, 828, 1080, 1280, 1668, 2048, 2560] | [640, 750, 828, 960, 1080, 1280, 1668, 1920, 2048, 2560, 3200, 3840, 4480, 5120, 6016]

添加于： astro@5.10.0

用于生成响应式图片的断点。需要为 layout 设置一个值。完整的列表通常不被使用，而是根据源和输出大小进行筛选。使用的默认值取决于使用的是本地图像服务还是远程图像服务。对于远程服务，使用更全面的列表，因为只生成所需的大小。对于本地服务，列表较短，以减少生成的图像数量。

Markdown 选项

markdown.shikiConfig

类型： Partial<ShikiConfig>

Shiki 是我们默认的语法高亮器。你可以通过 markdown.shikiConfig 对象配置所有选项

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      // Choose from Shiki's built-in themes (or add your own)
      // https://shiki.style/themes
      theme: 'dracula',
      // Alternatively, provide multiple themes
      // See note below for using dual light/dark themes
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // Disable the default colors
      // https://shiki.style/guide/dual-themes#without-default-color
      // (Added in v4.12.0)
      defaultColor: false,
      // Add custom languages
      // Note: Shiki has countless langs built-in, including .astro!
      // https://shiki.style/languages
      langs: [],
      // Add custom aliases for languages
      // Map an alias to a Shiki language ID: https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // Enable word wrap to prevent horizontal scrolling
      wrap: true,
      // Add custom transformers: https://shiki.style/guide/transformers
      // Find common transformers: https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});

用法和示例请参阅代码语法高亮指南。

markdown.syntaxHighlight

类型： SyntaxHighlightConfig | SyntaxHighlightConfigType | false
默认值： { type: 'shiki', excludeLangs: ['math'] }

用于 Markdown 代码块（```）的语法高亮器（如果有的话）。这决定了 Astro 将应用于你的 Markdown 代码块的 CSS 类。

shiki - 使用 Shiki 高亮器（默认配置为 github-dark 主题）
prism - 使用 Prism 高亮器并提供你自己的 Prism 样式表
false - 不应用语法高亮。

{
  markdown: {
    // Example: Switch to use prism for syntax highlighting in Markdown
    syntaxHighlight: 'prism',
  }
}

为了更好地控制语法高亮，你可以改为指定一个包含下面列出的属性的配置对象。

markdown.syntaxHighlight.type

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

添加于： astro@5.5.0

应用于 Markdown 代码块的默认 CSS 类。（如果不需要其他语法高亮配置，你可以直接将 markdown.syntaxHighlight 设置为 shiki、prism 或 false。）

markdown.syntaxHighlight.excludeLangs

类型： Array<string>
默认值： ['math']

添加于： astro@5.5.0

一个语言数组，用于从 markdown.syntaxHighlight.type 中指定的默认语法高亮中排除。这在使用从 Markdown 代码块创建图表的工具（如 Mermaid.js 和 D2）时非常有用。

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    syntaxHighlight: {
      type: 'shiki',
      excludeLangs: ['mermaid', 'math'],
    },
  },
});

markdown.remarkPlugins

类型： RemarkPlugins

传递 remark 插件来自定义 Markdown 的构建方式。你可以导入并应用插件函数（推荐），或将插件名称作为字符串传递。

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

markdown.rehypePlugins

类型： RehypePlugins

传递 rehype 插件来自定义 Markdown 输出的 HTML 的处理方式。你可以导入并应用插件函数（推荐），或将插件名称作为字符串传递。

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

markdown.gfm

类型： boolean
默认值： true

新增于： astro@2.0.0

Astro 默认使用 GitHub 风格的 Markdown。要禁用此功能，请将 gfm 标志设置为 false

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

类型： boolean
默认值： true

新增于： astro@2.0.0

Astro 默认使用 SmartyPants 格式化程序。要禁用此功能，请将 smartypants 标志设置为 false

{
  markdown: {
    smartypants: false,
  }
}

markdown.remarkRehype

类型： RemarkRehype

将选项传递给 remark-rehype。

{
  markdown: {
    // Example: Translate the footnotes text to another language, here are the default English values
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1"},
  },
};

i18n

类型： object

新增于： astro@3.5.0

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

有关 Astro 中国际化的更多信息，请参阅我们的指南

i18n.locales

类型： Locales

新增于： astro@3.5.0

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

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

不强制执行特定的语言代码格式或语法，但包含内容文件的项目文件夹必须与列表中的 locales 项完全匹配。在多个 codes 指向自定义 URL 路径前缀的情况下，将内容文件存储在与配置的 path 同名的文件夹中。

i18n.defaultLocale

类型： string

新增于： astro@3.5.0

你的网站/应用程序的默认语言环境，即指定的 locales 之一。这是一个必填字段。

不强制执行特定的语言格式或语法，但我们建议根据需要使用小写字母和连字符（例如“es”、“pt-br”）以获得最大的兼容性。

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

类型： object | "manual"
默认值： object

添加于： astro@3.7.0

控制路由策略以确定你的网站 URL。根据你的默认语言的文件夹/URL 路径配置来设置此项。

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

从 4.6.0 开始，此选项也可以设置为 manual。启用此路由策略后，Astro 将禁用其 i18n 中间件，并且不能配置其他 routing 选项（例如 prefixDefaultLocale）。你将负责编写自己的路由逻辑，或在你自己的逻辑旁边手动执行 Astro 的 i18n 中间件。

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr"],
    routing: "manual"
  }
})

i18n.routing.prefixDefaultLocale

类型： boolean
默认值： false

添加于： astro@3.7.0

当为 false 时，只有非默认语言会显示语言前缀。`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

配置当 prefixDefaultLocale: true 设置时，由 src/pages/index.astro 生成的主页 URL（/）是否重定向到 /[defaultLocale]。

设置 redirectToDefaultLocale: false 以禁用网站根目录下的此自动重定向

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

i18n.routing.fallbackType

类型： "redirect" | "rewrite"
默认值： "redirect"

新增于： astro@4.15.0

当配置了 i18n.fallback 以避免为缺失的页面路由显示 404 页面时，此选项控制是重定向到回退页面，还是重写回退页面的内容。

默认情况下，Astro 的 i18n 路由会根据你的回退配置创建页面，将访问者重定向到新的目标地址。浏览器将刷新并在 URL 栏中显示目标地址。

当配置 i18n.routing.fallback: "rewrite" 时，Astro 将创建页面，在原始请求的 URL 上呈现回退页面的内容。

使用以下配置，如果你有 src/pages/en/about.astro 文件但没有 src/pages/fr/about.astro 文件，`astro build` 命令将生成 dist/fr/about.html，其内容与 dist/en/about.html 页面相同。你的网站访问者将在 https://example.com/fr/about/ 看到页面的英文版本，并且不会被重定向。

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

i18n.domains

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

添加于： astro@4.3.0

将一种或多种受支持语言的 URL 模式配置为使用自定义域（或子域）。

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

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

export default defineConfig({
   site: "https://example.com",
   output: "server", // required, with no prerendered pages
   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"
    }
  },
})

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

有关更多详细信息，包括此功能的限制，请参阅国际化指南。

env

类型： object
默认值： {}

添加于： astro@5.0.0

用于类型安全环境变量的配置选项。

有关 Astro 中环境变量的更多信息，请参阅我们的指南。

env.schema

类型： EnvSchema
默认值： {}

添加于： astro@5.0.0

一个使用 envField 来定义你的环境变量的数据类型和属性的对象：`context`（客户端或服务器）、`access`（公共或私有）、要使用的 `default` 值，以及此环境变量是否为 `optional`（默认为 `false`）。

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

export default defineConfig({
  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" }),
    }
  }
})

envField 支持四种数据类型：字符串、数字、枚举和布尔值。`context` 和 `access` 是所有数据类型必需的属性。下面显示了每种数据类型的完整属性列表

import { envField } from "astro/config"

envField.string({
   // context & access
   optional: true,
   default: "foo",
   max: 20,
   min: 1,
   length: 13,
   url: true,
   includes: "oo",
   startsWith: "f",
   endsWith: "o",
})
envField.number({
   // context & access
   optional: true,
   default: 15,
   gt: 2,
   min: 1,
   lt: 3,
   max: 4,
   int: true,
})
envField.boolean({
   // context & access
   optional: true,
   default: true,
})
envField.enum({
   // context & access
   values: ['foo', 'bar', 'baz'], // required
   optional: true,
   default: 'baz',
})

env.validateSecrets

类型： boolean
默认值： false

添加于： astro@5.0.0

是否在启动开发服务器或运行构建时在服务器上验证私有变量。

默认情况下，在启动开发服务器或构建时，只有公共变量在服务器上进行验证，而私有变量仅在运行时进行验证。如果启用，私有变量也将在启动时进行检查。这在某些持续集成（CI）管道中很有用，可以确保在部署前所有私有变量都已正确设置。

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

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

贡献社区赞助

配置参考

顶级选项

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

build.concurrency

服务器选项

server.host

server.port

server.allowedHosts

server.open

server.headers

会话选项

session.driver

session.options

session.cookie

session.ttl

开发工具栏选项

devToolbar.enabled

预取选项

prefetch.prefetchAll

prefetch.defaultStrategy

图像选项

image.endpoint

image.service

image.service.config.limitInputPixels

image.domains

image.remotePatterns

image.responsiveStyles

image.layout

image.objectFit

image.objectPosition

image.breakpoints

Markdown 选项

markdown.shikiConfig

markdown.syntaxHighlight

markdown.syntaxHighlight.type

markdown.syntaxHighlight.excludeLangs

markdown.remarkPlugins

markdown.rehypePlugins

markdown.gfm

markdown.smartypants

markdown.remarkRehype

i18n

i18n.locales

i18n.defaultLocale

i18n.fallback

示例

i18n.routing

i18n.routing.prefixDefaultLocale

i18n.routing.redirectToDefaultLocale

i18n.routing.fallbackType

i18n.domains

env