跳转到内容

配置参考

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

// astro.config.mjs
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'

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

  • 'ignore' - 匹配 URL，而不管是否存在末尾的 /。对 "/about" 和 "/about/" 的请求将匹配到同样的路由。
  • 'always' - 只匹配包含末尾斜杠的 URL（例如："/about/"）。为了方便起见，在生产环境中，对于没有末尾斜杠的按需渲染 URL 的请求，将会重定向到正确的 URL。但是，在开发环境中，将会显示警示页面来提醒你，你已配置为 always 选项。
  • 'never' - 只匹配不包含末尾斜杠的 URL（例如："/about"）。为了方便起见，在生产环境中，对于包含末尾斜杠的按需渲染 URL 的请求，将会重定向到正确的 URL。但是，在开发环境中，将会显示警示页面来提醒你，你已配置为 never 选项。

当在生产环境中，因为 GET 请求发生重定向时，重定向将是 301（永久）重定向。而对于所有其他请求方法，则会是 308（永久，保留请求方法）重定向。

预渲染页面上的末尾斜杠是由托管平台处理的，他们可能会忽视你选择的配置。有关更多信息，请参阅托管平台的文档。此时，你不能使用 Astro 重定向 来处理这种情况。

{
  // 示例：在开发过程中要求有末尾斜杠
  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' // 注意，这是不支持的
	}
})

对于未安装适配器的静态生成站点，这将生成一个使用 <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 (EN), Netlify, Node.js, Vercel），或是探索 社区适配器 以在你的 Astro 项目中启用按需渲染。

有关 SSR 的更多信息，请参见我们的 按需渲染指南 以获得完整的 Astro 服务端渲染选项。

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

另见：

  • output

integrations

类型： AstroIntegration[]

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

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

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

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- 属性，会增加 +1 的特异性。

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

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

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

security

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

添加于： astro@4.9.0

为 Astro 网站启用安全措施。

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

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

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

security.checkOrigin

类型： boolean
默认值： true

添加于： 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 状态码，并不会渲染该页面。

security.allowedDomains

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

添加于： astro@5.14.2

定义了一个在使用 SSR 时允许的主机模式列表。配置后，Astro 会将 X-Forwarded-Host header 与这些模式进行验证以确保安全。如果 header 不符合任何允许的模式，则该 header 会被忽略，改用请求的原始主机。

这样可以防止主机 header 注入攻击，恶意行为者可能通过发送精心构造的 X-Forwarded-Host header 来操纵 Astro.url 的值。

每个模式可以指定 protocol、hostname 和 port。如果提供了这三项中的任意项，都会进行验证。模式支持通配符以实现灵活的主机名匹配：

{
  security: {
    // 示例：允许通过 HTTPS 访问 example.com 的任意子域
    allowedDomains: [
      {
        hostname: '**.example.com',
        protocol: 'https'
      },
      {
        hostname: 'staging.myapp.com',
        protocol: 'https',
        port: '443'
      }
    ]
  }
}

如果未配置，X-Forwarded-Host header 不会被信任并将被忽略。

vite

类型： ViteUserConfig

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

在 vite.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
默认值：'./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。

仅当其他减少总体渲染时间的尝试（例如，批处理或缓存长时间运行的任务，如网络请求或数据访问）无法实现或没有帮助时，才使用此选项。如果该值设置得太高，可能会由于内存资源不足以及 JS 单线程的原因，导致页面渲染变慢。

{
  build: {
    concurrency: 2
  }
}

:::caution[潜在的破坏性变更]此功能是稳定的，且不被认定为是实验性功能。但是，此功能仅旨在解决困难的性能问题，并且在 次要版本 中可能会产生破坏性变更，以尽可能保持此选项的性能。如果你正在使用此功能，请检查每个次要版本的 Astro 更新日志。:::

服务器选项

定制 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.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 响应标头。

Session 选项

添加于： astro@5.7.0

为你的 Astro 项目配置会话（session）存储。该功能用于以持久化方式存储会话数据，使其能够在不同请求之间被访问。部分适配器可能会提供默认的会话驱动，但你可以通过手动个人配置来覆盖它。

更多信息请参阅 session 指南。

  {
    session: {
      // Unstorage 上驱动的名字
      driver: 'redis',
      // 所需项取决于驱动程序
      options: {
        url: process.env.REDIS_URL,
      },
      ttl: 3600, // 1 小时
    }
  }

session.driver

类型： string | undefined

添加于： astro@5.7.0

Unstorage 上用于会话存储的驱动。Node、Cloudflare (EN) 和 Netlify 适配器都会为你自动配置默认的驱动，但是如果你更倾向于手动配置，或者是你正在使用的适配器并未提供驱动，你仍然可以自己指定。

该值为 Unstorage 驱动文档 的“驱动名称（Driver name）”。

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

:::note部分驱动可能需要安装额外的包。部分驱动可能会要求设置环境变量或凭证。更多信息请参阅 Unstorage 文档。:::

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: {
   // 如果设置为字符串，则该项会被视为 cookie 名称。
   cookie: "my-session-cookie",
 }
}
{
 session: {
   // 如果设置为对象，那么它将被视为 cookie 选项。
   cookie: {
     name: "my-session-cookie",
     sameSite: "lax",
     secure: true,
   }
 }
}

session.ttl

类型： number | undefined
默认值： Infinity

添加于： astro@5.7.0

一个可选的默认选项，用于配置会话值直到过期的生存时间（以秒为单位）。

默认情况下，会话值会一直存续直到它们被删除或是会话被销毁，并且由于特定的时间已经过去，因此它们也不会自动过期。通过设置 session.ttl 能为你的会话值添加一个默认的过期时间。将 ttl 选项传递给 session.set() 将覆盖该单个条目的全局默认值。

{
 session: {
   // 设置一个时长为 1 小时（3600 秒）的默认过期时间
   ttl: 3600,
 }
}

:::note为会话值设置 ttl 不会在时间限制传入后自动从存储中将其删除。

存储中的值只会在 ttl 时间过期后尝试访问它们时，才会被删除。而此时，会话值将会为 undefined，而直到这时会话值才会被删除。

部分驱动程序同样支持 ttl 选项，该选项将在指定时间后自动删除会话。有关更多信息，请参阅你选定驱动的文档。:::

开发工具栏选项

devToolbar.enabled

类型： boolean
默认值： true

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

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

devToolbar.placement

类型： 'bottom-left' | 'bottom-center' | 'bottom-right'
默认值： 'bottom-center'

添加于： astro@5.17.0

Astro 开发工具栏在屏幕上的默认位置。

工具栏的位置仍然可以通过工具栏设置界面更改。一旦更改，用户的偏好会保存在 localStorage 中，并覆盖此配置值。

Prefetch 选项

类型： 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 选项

image.endpoint

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

添加于： astro@3.1.0

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

{
  image: {
    // 示例：使用自定义的图像端点 `/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: {
    // 示例：通过自定义配置启用基于 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.service.config.kernel

类型： string | undefined
默认值： undefined

添加于： astro@5.17.0

Sharp 图像服务中用于 调整图像大小的默认内核。

默认情况下这是 undefined，对应于 Sharp 的默认内核 lanczos3。

image.domains

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

添加于： astro@2.10.10

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

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

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

image.remotePatterns

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

添加于： astro@2.10.10

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

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

  1. protocol
  2. hostname
  3. port
  4. pathname
{
  image: {
    // 示例：允许处理所有来自 aws s3 存储桶的图像
    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: {
      // 从 Shiki 的内置主题中选择 (或者添加你自己的)
      // https://shiki.style/themes
      theme: 'dracula',
      // 或者, 提供多个主题
      // 请参阅下面的注释，了解如何使用双明/暗主题
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // 禁用默认配色
      // https://shiki.style/guide/dual-themes#without-default-color
      // (添加于 v4.12.0)
      defaultColor: false,
      // 添加自定义语言
      // 注意：Shiki 内置了无数语言，包括 .astro！
      // https://shiki.style/languages
      langs: [],
      // 为语言添加自定义别名
      // 将别名映射到 Shiki 语言 ID：https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // 启用自动换行以防止水平滚动
      wrap: true,
      // 添加自定义转换器：https://shiki.style/guide/transformers
      // 在这里找到常用的转换器：https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});

请参阅 代码语法高亮指南 以获取更多用法和示例。

markdown.syntaxHighlight

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

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

{
  markdown: {
    // 示例：在 Markdown 中使用 prism 进行语法高亮显示
    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 输出内容的处理方式。你可以导入并应用插件函数（推荐），或传递一个值为插件名的字符串。

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.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 时，只有非默认语言的 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 可以在你的网站根目录禁用这个自动重定向：

// astro.config.mjs
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 页面时，此选项用于控制是将用户重定向到回退页面，还是将回退页面的内容重写到原始请求的 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/ 看到页面的英文版本，而不会被重定向。

//astro.config.mjs
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。

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

//astro.config.mjs
export default defineConfig({
	 site: "https://example.com",
	 output: "server", // 必须，没有预渲染页面
	 adapter: node({
	   mode: 'standalone',
	 }),
	 i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    prefixDefaultLocale: false,
    domains: {
      fr: "https://fr.example.com",
      es: "https://example.es"
    }
  },
})

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

请参阅 国际化指南 了解更多详情，包括此功能的限制。

env

类型： object
默认值： {}

添加于： astro@5.0.0

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

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

env.schema

类型： EnvSchema
默认值： {}

添加于： astro@5.0.0

使用 envField 定义环境变量的数据类型和属性：context（client 或 server）、access（public 或 secret）、要使用的 default 值，以及此环境变量是否是 optional（默认为 false）。

// astro.config.mjs
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 支持四种数据类型：string、number、enum 和 boolean。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'], // 必需
   optional: true,
   default: 'baz',
})

env.validateSecrets

类型： boolean
默认值： false

添加于： astro@5.0.0

当启动 dev 服务器或运行构建时，是否在服务器上验证私密环境变量。

默认情况下，只有在启动 dev 服务器或运行构建时才会在服务器上验证公共变量，私密变量只在运行时验证。如果启用，私密变量也将在启动时检查。这在某些持续集成（CI）管道中很有用，以确保在部署之前正确设置所有的私密信息。

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

export default defineConfig({
  env: {
    schema: {
      // ...
    },
    validateSecrets: true
  }
})
贡献 社区 赞助