Question

可以通过在你的项目中添加一个 astro.config.mjs 文件来自定义 Astro 的运行方式。它是 Astro 项目中的常见文件，所有官方的示例模板和主题都默认包含该文件。

阅读 Astro API 的配置参考以概览所有支持的配置项。

Astro 配置文件

一个有效的 Astro 配置文件使用 default 导出其配置，推荐使用 defineConfig 助手函数。

astro.config.mjs

import { defineConfig } from 'astro/config'


export default defineConfig({
  // 你的配置项都在这里
  // https://docs.astro.buildhttps://www.wenjiangs.com/doc/astro-reference-configuration-reference
})

推荐使用 defineConfig() 以便 IDE 可以提供自动类型提示，但这并非是必须的。一个最基本的有效配置文件应该是这样：

astro.config.mjs

// 示例：最基础完全空白的配置文件
export default {}

受支持的配置文件类型

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

TypeScript 配置文件使用 tsm 解析并会遵循你项目中的 tsconfig 选项。

配置文件解析

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

# 示例：从 ./astro.config.mjs 中读取配置
astro build

你也可以用 --config CLI 标志明确指出要使用的配置文件。这个 CLI 标志将基于你运行 astro 命令的目录进行解析。

# 示例：从这个文件中读取配置
astro build --config my-config-file.js

配置智能提示

Astro 建议在配置文件中使用 defineConfig() 助手函数。IDE 将借助 defineConfig() 为你提供智能提示。像 VSCode 这样的编辑器就能够读取 Astro 的 TypeScript 类型定义并自动提供 jsdoc 类型提示，即使你的配置文件不是用 TypeScript 写的。

astro.config.mjs

import { defineConfig } from 'astro/config'


export default defineConfig({
  // 你的配置项都在这里
  // https://docs.astro.buildhttps://www.wenjiangs.com/doc/astro-reference-configuration-reference
})

你也可以使用 JSDoc 标注，手动向 VSCode 提供类型定义。

astro.config.mjs

 export default /** @type {import('astro').AstroUserConfig} */ ({
  // 你的配置项都在这里
  // https://docs.astro.buildhttps://www.wenjiangs.com/doc/astro-reference-configuration-reference
}

引用相对文件

如果你提供了 root 相对路径或 --root CLI 标志，Astro 将基于你运行 astro 命令的目录来解析。

astro.config.mjs

import { defineConfig } from 'astro/config'


export default defineConfig({
  // 基于你当前的工作目录解析 "./foo" 目录
  root: 'foo'
})

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

astro.config.mjs

import { defineConfig } from 'astro/config'


export default defineConfig({
  //  基于你当前的工作目录解析 "./foo" 目录
  root: 'foo',
  //  基于你当前的工作目录解析 "./foo/public" 目录
  publicDir: 'public',
})

使用 import.meta.url 引用相对于配置文件的文件或目录（除非你正在编写 common.js 模块标准的 astro.config.cjs 文件）。

astro.config.mjs

import { defineConfig } from 'astro/config'


export default defineConfig({
    // 基于配置文件解析 "./foo" 目录
    root: new URL("./foo", import.meta.url).toString(),
    // 基于配置文件解析 "./public" 目录
    publicDir: new URL("./public", import.meta.url)..toString(),
})

注意

Vite 特定的 import.meta 属性，如 import.meta.env 或 import.meta.glob，无法在你的配置文件中访问。我们推荐使用 dotenv 或 fast-glob 作为替代方案。此外，tsconfig 路径别名 将不会被解析。在该文件中，对模块的导入应使用相对路径。

自定义输出文件名

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

astro.config.mjs

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

环境变量

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

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

你也可以使用 Vite 的 loadEnv 助手函数来手动加载 .env 文件。

astro.config.mjs

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

配置参考

阅读 Astro API 的配置参考以概览所有支持的配置选项。