配置 Astro

通过在项目中添加 astro.config.mjs 文件来自定义 Astro 的工作方式。这是 Astro 项目中的一个常见文件，所有官方示例模板和主题都默认附带一个。

¥Customize how Astro works by adding an astro.config.mjs file in your project. This is a common file in Astro projects, and all official example templates and themes ship with one by default.

Read Astro’s API configuration reference for a full overview of all supported configuration options.

Astro 配置文件

¥The Astro Config File

有效的 Astro 配置文件使用 default 导出来导出其配置，并使用推荐的 defineConfig 辅助程序：

¥A valid Astro config file exports its configuration using the default export, using the recommended defineConfig helper:

import { defineConfig } from 'astro/config'

export default defineConfig({
  // your configuration options here...
  // https://astro.nodejs.cn/en/reference/configuration-reference/
})

建议在 IDE 中使用 defineConfig() 进行自动类型提示，但它也是可选的。一个绝对简单、有效的配置文件如下所示：

¥Using defineConfig() is recommended for automatic type hints in your IDE, but it is also optional. An absolutely bare-minimum, valid configuration file would look like this:

// Example: Bare minimum, empty configuration file
export default {}

支持的配置文件类型

¥Supported Config File Types

Astro 支持多种 JavaScript 配置文件格式：astro.config.js、astro.config.mjs、astro.config.cjs 和 astro.config.ts。我们建议在大多数情况下使用 .mjs，如果你想在配置文件中编写 TypeScript，我们建议使用 .ts。

¥Astro supports several file formats for its JavaScript configuration file: astro.config.js, astro.config.mjs, astro.config.cjs and astro.config.ts. We recommend using .mjs in most cases or .ts if you want to write TypeScript in your config file.

TypeScript 配置文件加载是使用 tsm 处理的，并且会尊重你的项目 tsconfig 选项。

¥TypeScript config file loading is handled using tsm and will respect your project tsconfig options.

配置文件解析

¥Config File Resolving

Astro 将自动尝试解析项目根目录中名为 astro.config.mjs 的配置文件。如果在项目根目录中没有找到配置文件，则将使用 Astro 的默认选项。

¥Astro will automatically try to resolve a config file named astro.config.mjs inside project root. If no config file is found in your project root, Astro’s default options will be used.

# Example: Reads your configuration from ./astro.config.mjs
astro build

你可以显式设置一个配置文件以与 --config CLI 标志一起使用。此 CLI 标志始终相对于你运行 astro CLI 命令的当前工作目录进行解析。

¥You can explicitly set a config file to use with the --config CLI flag. This CLI flag always resolves relative to the current working directory where you ran the astro CLI command.

# Example: Reads your configuration from this file
astro build --config my-config-file.js

配置智能感知

¥Config IntelliSense

Astro 建议在配置文件中使用 defineConfig() 辅助程序。defineConfig() 在你的 IDE 中提供自动 IntelliSense。VSCode 等编辑器能够读取 Astro 的 TypeScript 类型定义并提供自动 jsdoc 类型提示，即使你的配置文件不是用 TypeScript 编写的。

¥Astro recommends using the defineConfig() helper in your configuration file. defineConfig() provides automatic IntelliSense in your IDE. Editors like VSCode are able to read Astro’s TypeScript type definitions and provide automatic jsdoc type hints, even if your configuration file isn’t written in TypeScript.

import { defineConfig } from 'astro/config'

export default defineConfig({
  // your configuration options here...
  // https://astro.nodejs.cn/en/reference/configuration-reference/
})

你还可以使用以下 JSDoc 表示法手动向 VSCode 提供类型定义：

¥You can also provide type definitions manually to VSCode, using this JSDoc notation:

export default /** @type {import('astro').AstroUserConfig} */ {
  // your configuration options here...
  // https://astro.nodejs.cn/en/reference/configuration-reference/
}

引用相关文件

¥Referencing Relative Files

如果你提供 root 或 --root CLI 标志的相对路径，Astro 将根据你运行 astro CLI 命令的当前工作目录来解析它。

¥If you provide a relative path to root or the --root CLI flag, Astro will resolve it against the current working directory where you ran the astro CLI command.

import { defineConfig } from 'astro/config'

export default defineConfig({
  // Resolves to the "./foo" directory in your current working directory
  root: 'foo'
})

Astro 将解析相对于项目根目录的所有其他相关文件和目录字符串：

¥Astro will resolve all other relative file and directory strings as relative to the project root:

import { defineConfig } from 'astro/config'

export default defineConfig({
  // Resolves to the "./foo" directory in your current working directory
  root: 'foo',
  // Resolves to the "./foo/public" directory in your current working directory
  publicDir: 'public',
})

要引用与配置文件相关的文件或目录，请使用 import.meta.url（除非你正在编写 common.js astro.config.cjs 文件）。

¥To reference a file or directory relative to the configuration file, use import.meta.url (unless you are writing a common.js astro.config.cjs file).

import { defineConfig } from 'astro/config'

export default defineConfig({
  // Resolves to the "./foo" directory, relative to this config file
  root: new URL("./foo", import.meta.url).toString(),
  // Resolves to the "./public" directory, relative to this config file
  publicDir: new URL("./public", import.meta.url).toString(),
})

自定义输出文件名

¥Customising Output Filenames

对于 Astro 处理的代码（例如导入的 JavaScript 或 CSS 文件），你可以在 astro.config.* 文件的 vite.build.rollupOptions 条目中使用 entryFileNames、chunkFileNames 和 assetFileNames 自定义输出文件名。

¥For code that Astro processes, like imported JavaScript or CSS files, you can customise output filenames using entryFileNames, chunkFileNames, and assetFileNames in a vite.build.rollupOptions entry in your astro.config.* file.

import { defineConfig } from 'astro/config'

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: 'entry.[hash].mjs',
          chunkFileNames: 'chunks/chunk.[hash].mjs',
          assetFileNames: 'assets/asset.[hash][extname]',
        },
      },
    },
  },
})

如果你的脚本的名称可能会受到广告拦截器的影响（例如 ads.js 或 google-tag-manager.js），这会很有帮助。

¥This can be helpful if you have scripts with names that might be impacted by ad blockers (e.g. ads.js or google-tag-manager.js).

环境变量

¥Environment Variables

Astro 在加载其他文件之前会评估配置文件。因此，你无法使用 import.meta.env 访问 .env 文件中设置的环境变量。

¥Astro evaluates configuration files before it loads your other files. As such, you can’t use import.meta.env to access environment variables that were set in .env files.

你可以在配置文件中使用 process.env 来访问其他环境变量，例如由 CLI 设置。

¥You can use process.env in a configuration file to access other environment variables, like those set by the CLI.

你还可以使用 Vite 的 loadEnv 帮手手动加载 .env 文件。

¥You can also use Vite’s loadEnv helper to manually load .env files.

pnpm does not allow you to import modules that are not directly installed in your project. If you are using pnpm, you will need to install vite to use the loadEnv helper.

pnpm add vite --save-dev

import { loadEnv } from "vite";
const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

配置参考

¥Configuration Reference

Read Astro’s API configuration reference for a full overview of all supported configuration options.