Astro 项目结构

目录结构

创建空项目后，目录大致如下。

my-astro-blog/
├── src/
│   ├── components/   # 可复用的 UI 组件
│   ├── layouts/      # 页面布局模板
│   ├── pages/        # 页面与路由（核心）
│   └── styles/       # 全局样式
├── public/           # 不经过打包的静态资源
├── astro.config.mjs  # Astro 配置文件
├── package.json
└── tsconfig.json

下面逐个说明。

src/pages 页面目录

src/pages/ 是 Astro 的路由根目录，这里的每个文件都会映射成一个网址：

src/pages/index.astro 对应网站首页 /
src/pages/about.astro 对应 /about
src/pages/blog/post1.md 对应 /blog/post1

你几乎不需要手动配置路由表，文件放哪，网址就是哪。

你可能会注意到，例子里既有 .astro 又有 .md，两种格式的定位不同。

.astro 是 Astro 自带的组件文件，由「组件脚本（--- 之间）+ HTML 模板」组成，适合需要自定义结构、引入组件、写逻辑的页面，比如首页、关于页、文章列表页。
.md 是 Markdown 文件，本质是用来「写文章」的纯文本格式，Astro 会把它渲染成 HTML 页面，常用于博客文章、文档这类以文字为主的内容。你只需写正文，排版交给 Markdown 语法，统一的页面外壳通过内容集合或文件 front-matter 里的 layout 字段来套用。

简单说，要「搭页面、写逻辑」用 .astro，要「写文章、出内容」用 .md，它们最终都会变成网址，只是书写方式和适用场景不同。

src/components 组件目录

这里放可复用的界面片段，比如导航栏、卡片、页脚，组件可以是 .astro 文件，也可以是 React、Vue 等框架的组件。

例如一个 Card.astro：

---
// src/components/Card.astro
const { title } = Astro.props; // Astro 是自动注入的内置全局对象（见 Astro 全局对象 /528），props 读取外部传入的属性（见 Astro Props /508）
---
<div class="card">
  <h3>{title}</h3>
  <slot />
</div>

src/layouts 布局目录

布局是「套在页面外面的壳」，通常包含 <html>、<head>、导航、页脚等公共部分，页面只需关注自己的正文内容。

---
// src/layouts/BaseLayout.astro
const { title } = Astro.props;
---
<html lang="zh-CN">
  <head><title>{title}</title></head>
  <body>
    <nav>这里是导航</nav>
    <main><slot /></main>
    <footer>这里是页脚</footer>
  </body>
</html>

public 静态资源目录

放在 public/ 里的文件会被原样复制到最终站点的根目录，不会被 Astro 处理，适合放 favicon.ico、域名验证文件、已压缩好的图片等。

在页面里引用时，路径从根目录写起。

<link rel="icon" href="/favicon.ico" />

src/styles 全局样式

这里放全站通用的 CSS，也可以在组件里写局部样式，后文会详细讲。

astro.config.mjs 配置文件

项目的核心配置都在这里，比如站点地址、集成（integrations）、Markdown 插件等。

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

export default defineConfig({
  site: 'https://example.com',
});

tsconfig.json

Astro 内置了对 TypeScript 的支持，这个文件让编辑器能提供类型提示，你也可以在这里配置路径别名。

Astro 全局对象

Astro 常用命令