配置概览

Astro 是一个灵活、自由的框架，它允许你以多种不同的方式来配置你的项目。这意味着开始一个新项目可能会让人感到不知所措：因为没有“一个最好的方法”来设置你的 Astro 项目！

这个“配置”部分中的指南将帮助你熟悉各种文件，这些文件允许你配置和自定义项目和开发环境的各个方面。

如果这是你的第一个 Astro 项目，或者你已经有一段时间没有建立新项目了，请使用以下指南和文档中的参考来获取帮助。

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

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

Astro 配置文件

Astro 配置文件是一个 JavaScript 文件，它被包含在每个起始项目的根目录中：

import { defineConfig } from 'astro/config'

export default defineConfig({
  // 你的配置项都在这里
})

仅当你需要配置某些内容时才需要此文件，但大多数项目都会使用此文件。 defineConfig() 助手函数在你的 IDE 中提供自动化的 IntelliSense，你可以在其中添加所有配置选项，以告诉 Astro 如何构建项目并将其渲染为 HTML。

我们建议在大多数情况下使用默认文件格式 .mjs，如果你想在配置文件中编写 TypeScript，则使用 .ts。但是，也支持 astro.config.js 和 astro.config.cjs。

阅读 Astro 的配置参考，了解所有支持的配置选项的完整概述。

TypeScript 配置文件

每个 Astro 起始项目都包含了一个 tsconfig.json 文件。Astro 的组件脚本就是 Typescript，它提供 Astro 的编辑器工具，并允许你可选地向 JavaScript 添加语法，以对你自己的项目代码进行类型检查。

使用 tsconfig.json 文件配置 TypeScript 模板，该模板将对代码执行类型检查、配置 TypeScript 插件、设置导入别名等。

阅读 Astro 的 TypeScript 指南，了解 TypeScript 选项和 Astro 内置实用程序类型的完整概述。

开发体验

当你处在开发模式下工作时，你可以利用代码编辑器和其他工具来改善 Astro 开发者的体验。

Astro 提供了自己的官方 VS Code 扩展，并且与其他几种流行的编辑器工具兼容。Astro 还提供了一个可自定义的工具栏，当开发服务器运行时，该工具栏会显示在浏览器预览中。你可以安装甚至构建自己的工具栏应用程序以获得附加功能。

参阅 Astro 的编辑器设置选项和使用开发工具栏指南，了解如何自定义你的开发体验。

新项目常见事宜

以下是你在面对一个新的 Astro 项目时，可能会考虑的一些初始步骤。

添加你的部署域名

要生成站点地图并创建规范 URL，可以在 site 选项中配置部署 URL。如果你要部署到一个路径（例如 www.example/docs），你还可以为项目的根目录配置 base。

此外，部署时不同的 host 对于 URL 末尾的尾部斜杠可能有不同的行为。（例如 example.com/about 与 example.com/about/）。当部署站点后，你可能需要配置 trailingSlash 偏好。

import { defineConfig } from 'astro/config'

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

添加站点元数据

Astro 不会将其配置文件用于常见的 SEO 或元数据，它们仅用于构建项目代码并将其渲染为 HTML 所需的信息。

相反，这些信息会被添加到页面中的 <head> 部分并放在 HTML 的 <link> 和 <meta> 标签中，就像编写纯 HTML 页面一样。

Astro 站点的一种常见做法是创建一个 <Head /> .astro 组件，该组件可以添加到通用的布局组件中，以便应用于你所有的页面。

---
import Head from './Head.astro';
const { ...props } = Astro.props;
---
<html>
  <head>
    <meta charset="utf-8">
    <Head />
    <!-- -->
  </head>
  <body><!-- --></body>
</html>

因为 Head.astro 只是一个常规的 Astro 组件，所以你可以导入文件并接收从其他组件传递的 props，例如特定的页面标题。

---
import Favicon from '../assets/Favicon.astro';
import SomeOtherTags from './SomeOtherTags.astro';
const { title = 'My Astro Website', ...props } = Astro.props;
---
<link rel="sitemap" href="/sitemap-index.xml">
<title>{title}</title>
<meta name="description" content="Welcome to my new Astro site!">

<!-- 网站分析 -->
<script data-goatcounter="https://my-account.goatcounter.com/count" async src="//gc.zgo.at/count.js"></script>

<!-- 开放图谱标签 -->
<meta property="og:title" content="My New Astro Website" />
<meta property="og:type" content="website" />
<meta property="og:url" content="http://www.example.com/" />
<meta property="og:description" content="Welcome to my new Astro site!" />
<meta property="og:image" content="https://www.example.com/_astro/seo-banner.BZD7kegZ.webp">
<meta property="og:image:alt" content="">

<SomeOtherTags />

<Favicon />