首页 / Astro 教程 / 配置 astro.config 总览

← 上一篇 下一篇 →
Astro 教程

配置 astro.config 总览

本教程共 56 篇 · 第 41 篇 · 更新于 2026-08-07 · 约 9 分钟阅读

AstroAstro 教程配置astro.configsiteoutputintegrations

本节目标：看清 astro.config 文件的作用，以及常用配置项（site、base、trailingSlash、output、integrations 等）分别管什么。

每个 Astro 项目根目录都有一份配置文件，通常叫 astro.config.mjs。它告诉 Astro”你的项目怎么构建、怎么渲染”。本章做一张”配置地图”，不逐个列完所有项（那是官方参考文档的活），只讲最常用的几块，让你知道去哪找。

配置文件长什么样

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  // 你的配置项写这里
});

defineConfig() 不是必须，但加上后编辑器有自动补全（IntelliSense），写起来省心。推荐用 .mjs 格式；想写 TypeScript 就用 .ts；.js 也支持。只有当你”有东西要配”时才需要它，但绝大多数项目都会用到。

Note

Astro 是”灵活、不强制”的框架，没有唯一正确的配置方式。起步觉得选项多很正常，挑你要用的配就好。

最常先配的：site 和 base

site 填你的线上域名，用于生成 sitemap 和规范的 URL（canonical URL）。如果站点挂在子路径（如 www.example.com/docs），再加 base：

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://www.example.com",
  base: "/docs",
  trailingSlash: "always",
});

trailingSlash 管网址末尾斜杠的行为（example.com/about 还是 example.com/about/）。不同部署平台默认行为不一，部署后若发现链接错乱，常从这里调。

输出与渲染：output

output 决定页面生成时机，三个值：

  • 'static'（默认）：全静态，构建时生成。
  • 'server'：整站按需渲染（SSR）。
  • 'hybrid'：默认静态、个别路由按需。

它必须和适配器配套（第 36、40 章），是按需渲染的总开关。

加功能：integrations

所有集成、适配器都通过 integrations 数组接入（第 39 章）：

integrations: [react(), sitemap()]

Astro 不负责 SEO 元数据

这是个容易误会的点：配置文不放普通的 SEO 或 meta 信息，它只放”构建项目代码所需”的信息。标题、描述、OG 图等，要像写普通 HTML 那样放进页面 <head>，用 <link>、<meta> 标签。常见做法是建一个 <Head /> 组件，再塞进通用布局里，所有页面共享：

---
// src/components/Head.astro
import Favicon from "../assets/Favicon.astro";
const { title = "My Astro Website", ...props } = Astro.props;
---
<title>{title}</title>
<meta name="description" content="Welcome to my new Astro site!">
<meta property="og:title" content="My New Astro Website" />
<Favicon />

这样每个页面传个不同 title 进去即可，不必每页重写一遍。

另外两个配套文件

除了 astro.config.mjs，项目里还有两个常一起出现的配置：

  • tsconfig.json：管 TypeScript（第 43 章）。Astro 的组件脚本本身就是 TypeScript，这个文件让编辑器和构建工具理解你的项目。
  • package.json：管依赖和脚本（如 npm run dev）。

三者分工明确：配置管”怎么构建”，tsconfig 管”类型怎么检查”，package.json 管”依赖和命令”。

开发体验相关

开发时你能借助编辑器插件和开发工具栏（第 44 章）提升效率。这些不是配置文件的必选项，但值得了解。例如开发工具栏的开关也是在 astro.config.mjs 里设置的：

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  devToolbar: {
    enabled: false, // 关闭开发工具栏
  },
});

还能配哪些常用项

配置项很多，挑几个你可能用到的：

  • vite：把选项透传给底层打包工具 Vite，比如自定义别名、插件。
  • prefetch：开启预获取（第 46 章），让链接在 hover / 进入视口时提前加载。
  • image：配置图片服务（第 23 章），比如默认图片格式、尺寸。
  • markdown / mdx：配置 Markdown 渲染，比如用哪些 remark / rehype 插件。
  • scopedStyleStrategy：组件样式作用域的策略（where / class / attribute）。
  • build：构建相关，比如 build.format 控制输出文件后缀。

这些不用一次配齐，用到哪块功能再回来加。

一个较完整的示例

把前面提到的项凑一起看个轮廓（非必须全用）：

// astro.config.mjs
import { defineConfig } from "astro/config";
import react from '@astrojs/react';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: "https://www.example.com",
  base: "/docs",
  trailingSlash: "always",
  output: 'static',
  integrations: [react(), sitemap()],
  prefetch: { defaultStrategy: 'viewport' },
  scopedStyleStrategy: 'where',
});

看到这里你应该明白：astro.config.mjs 就是”按需求往里加开关”。

配置和部署的关系

site 和 base 直接影响部署后的链接是否正确。举例：你部署到 www.example.com/docs 子路径，却没设 base: "/docs"，那么页面里 /about 这类绝对路径会指向根域名的 /about，而不是 /docs/about，导致资源 404。所以部署前先确认 site 和 base 填对，是不少”上线后样式/脚本丢失”问题的根源。

常见配置遗漏

新手常漏的几项：

  • 忘了 site，sitemap 生成的链接是错的。
  • 子路径部署忘了 base，资源路径错乱。
  • 开了按需渲染却没在 output 里配对，也没装适配器（第 36、40 章）。
  • 想做类型检查却没配 tsconfig.json 的 extends。

这些都不是语法错误，而是”运行时才暴露”的坑，提前在配置里想清楚最省事。

配置写错怎么办

配置文件本质是 JavaScript，astro dev / astro build 启动时若配置有语法或导入错误，会直接报出来。多数情况是 import 路径写错、或工厂函数没加 ()。读报错信息里的行号，定位很快。

配置改动后要重启吗

改了 astro.config.mjs 或 tsconfig.json，一般要重启开发服务器（astro dev）才会完全生效——Astro 不会热替换配置。这是新手常踩的”我明明改了配置怎么没反应”：不是没生效，是没重启。改动后顺手 Ctrl+C 再 npm run dev 一下最稳。

多环境配置

本地、测试、生产可能要用不同 site、不同 API 地址。Astro 支持用环境变量或不同配置文件区分。常见做法是在 astro.config.mjs 里读 import.meta.env（第 35 章）来切换值，或者配合 --config 标志加载另一份配置文件。不用把三套配置写死，按环境读变量即可。

用 .ts 还是 .mjs

配置默认是 .mjs（标准 ES 模块）。若你想在配置里写 TypeScript（比如给配置项加类型），可改用 .ts，Astro 支持直接读取。两者功能一样，选你顺手的。注意：配置文件里写的 TS 只在构建时被 Astro 处理，不必额外编译步骤。defineConfig() 的括号别漏——它是函数调用，不是对象字面量。

一份”最小可用配置”长啥样

如果项目很简单、暂时不需要任何花哨功能，最小配置甚至可以只有空对象：

import { defineConfig } from "astro/config";
export default defineConfig({});

这等价于”全部用默认”：静态输出、无集成。等你哪天需要 sitemap、需要按需渲染、需要改域名，再往里加对应开关即可。配置不是一次性写满的，而是随项目成长逐步补。

小结

astro.config.mjs 是项目的”总开关”。常用项：site / base / trailingSlash 管域名与链接；output 管渲染模式；integrations 管功能扩展；devToolbar 管开发工具栏。SEO 元数据不放这里、要放进页面 <head>。完整配置项清单见官方配置参考，用到时再去查。

下一章我们看命令行：平时开发、构建、检查类型，都靠哪几条命令。

上一篇
适配器（Adapters）与部署目标
下一篇
CLI 命令