项目结构 #

一、默认目录结构 #

一个标准的 Astro 项目目录结构如下：

text

my-project/
├── public/
│   ├── favicon.svg
│   └── images/
├── src/
│   ├── components/
│   │   └── Card.astro
│   ├── layouts/
│   │   └── Layout.astro
│   ├── pages/
│   │   └── index.astro
│   └── content/
│       └── config.ts
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── README.md

二、核心目录详解 #

2.1 src 目录 #

src 目录是项目的源代码目录，包含所有页面、组件、布局等。

text

src/
├── components/     # 可复用组件
├── layouts/        # 页面布局组件
├── pages/          # 页面文件（路由）
├── content/        # 内容集合
├── styles/         # 全局样式
└── utils/          # 工具函数

2.2 pages 目录 #

pages 目录是 Astro 的核心目录，文件即路由：

text

src/pages/
├── index.astro          → /
├── about.astro          → /about
├── contact.astro        → /contact
├── blog/
│   ├── index.astro      → /blog
│   ├── [slug].astro     → /blog/:slug
│   └── [id].astro       → /blog/:id
├── 404.astro            → /404
└── rss.xml.js           → /rss.xml

路由规则：

文件路径	生成的路由
`index.astro`	`/`
`about.astro`	`/about`
`blog/index.astro`	`/blog`
`blog/[slug].astro`	`/blog/:slug`

2.3 components 目录 #

存放可复用的 UI 组件：

text

src/components/
├── Header.astro
├── Footer.astro
├── Navigation.astro
├── Card.astro
├── Button.astro
└── ui/
    ├── Input.astro
    └── Select.astro

组件示例：

astro

---
// src/components/Card.astro
interface Props {
  title: string;
  description: string;
}

const { title, description } = Astro.props;
---

<div class="card">
  <h3>{title}</h3>
  <p>{description}</p>
</div>

<style>
  .card {
    padding: 1rem;
    border: 1px solid #ddd;
    border-radius: 8px;
  }
</style>

2.4 layouts 目录 #

存放页面布局组件：

text

src/layouts/
├── Layout.astro          # 基础布局
├── BlogLayout.astro      # 博客布局
└── DocsLayout.astro      # 文档布局

布局示例：

astro

---
// src/layouts/Layout.astro
interface Props {
  title: string;
}

const { title } = Astro.props;
---

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{title}</title>
  </head>
  <body>
    <slot />
  </body>
</html>

2.5 content 目录 #

存放内容集合配置和 Markdown 文件：

text

src/content/
├── config.ts             # 内容集合配置
├── blog/
│   ├── post-1.md
│   ├── post-2.md
│   └── post-3.md
└── docs/
    ├── intro.md
    └── guide.md

内容集合配置：

typescript

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.date(),
    tags: z.array(z.string()),
    draft: z.boolean().default(false),
  }),
});

export const collections = {
  blog: blogCollection,
};

2.6 public 目录 #

存放静态资源文件，不会被构建处理：

text

public/
├── favicon.svg           # 网站图标
├── images/
│   ├── logo.png
│   └── hero.jpg
├── fonts/
│   └── custom-font.woff2
└── robots.txt            # 爬虫配置

public 目录特点：

特点	说明
直接复制	文件直接复制到输出目录
无处理	不经过构建处理
路径访问	通过根路径直接访问
静态资源	适合图片、字体、图标等

三、配置文件 #

3.1 astro.config.mjs #

Astro 主配置文件：

javascript

import { defineConfig } from 'astro/config';

export default defineConfig({
  // 项目根目录
  root: '.',
  
  // 输出目录
  outDir: 'dist',
  
  // 站点 URL
  site: 'https://example.com',
  
  // 输出模式
  output: 'static', // 'static' | 'server' | 'hybrid'
  
  // 集成配置
  integrations: [],
  
  // Vite 配置
  vite: {},
});

3.2 package.json #

项目依赖和脚本配置：

json

{
  "name": "my-astro-project",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "astro": "^4.0.0"
  },
  "devDependencies": {
    "@astrojs/check": "^0.3.0",
    "typescript": "^5.3.0"
  }
}

3.3 tsconfig.json #

TypeScript 配置：

json

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"]
    }
  }
}

四、文件命名规范 #

4.1 组件命名 #

text

推荐：
├── Header.astro          # PascalCase
├── Navigation.astro
├── BlogCard.astro
└── UserAvatar.astro

不推荐：
├── header.astro          # camelCase
├── navigation.astro
├── blog-card.astro       # kebab-case
└── user_avatar.astro     # snake_case

4.2 页面命名 #

text

推荐：
├── index.astro           # 小写
├── about.astro
├── blog-post.astro       # kebab-case
└── [slug].astro          # 动态路由

不推荐：
├── Index.astro           # 大写
├── About.astro
└── blogPost.astro        # camelCase

4.3 目录命名 #

text

推荐：
├── components/           # 小写复数
├── layouts/
├── pages/
└── utils/

不推荐：
├── Components/           # 大写
├── layout/               # 单数
└── Utils/

五、路径别名配置 #

5.1 配置别名 #

在 tsconfig.json 中配置路径别名：

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"],
      "@pages/*": ["src/pages/*"],
      "@styles/*": ["src/styles/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

5.2 使用别名 #

astro

---
// 使用别名导入
import Layout from '@layouts/Layout.astro';
import Card from '@components/Card.astro';
import Button from '@components/ui/Button.astro';
---

<Layout title="首页">
  <Card title="标题" description="描述" />
  <Button>点击</Button>
</Layout>

六、项目结构最佳实践 #

6.1 小型项目结构 #

text

small-project/
├── public/
├── src/
│   ├── components/
│   ├── layouts/
│   └── pages/
├── astro.config.mjs
└── package.json

6.2 中型项目结构 #

text

medium-project/
├── public/
│   ├── images/
│   └── fonts/
├── src/
│   ├── components/
│   │   ├── common/
│   │   └── ui/
│   ├── layouts/
│   ├── pages/
│   │   ├── blog/
│   │   └── docs/
│   ├── content/
│   ├── styles/
│   └── utils/
├── astro.config.mjs
├── tsconfig.json
└── package.json

6.3 大型项目结构 #

text

large-project/
├── public/
│   ├── images/
│   ├── fonts/
│   └── icons/
├── src/
│   ├── components/
│   │   ├── common/
│   │   ├── ui/
│   │   ├── blog/
│   │   └── docs/
│   ├── layouts/
│   │   ├── Layout.astro
│   │   ├── BlogLayout.astro
│   │   └── DocsLayout.astro
│   ├── pages/
│   │   ├── blog/
│   │   ├── docs/
│   │   └── api/
│   ├── content/
│   │   ├── blog/
│   │   └── docs/
│   ├── styles/
│   │   ├── global.css
│   │   └── variables.css
│   ├── utils/
│   │   ├── helpers.ts
│   │   └── constants.ts
│   └── types/
│       └── index.ts
├── astro.config.mjs
├── tsconfig.json
└── package.json

七、构建输出 #

7.1 静态构建输出 #

text

dist/
├── index.html
├── about/
│   └── index.html
├── blog/
│   ├── index.html
│   ├── post-1/
│   │   └── index.html
│   └── post-2/
│       └── index.html
├── _astro/
│   ├── index.css
│   └── index.js
└── images/
    └── logo.png

7.2 SSR 构建输出 #

text

dist/
├── server/
│   ├── entry.mjs
│   └── chunks/
├── client/
│   ├── _astro/
│   └── images/
└── renderers/

八、总结 #

Astro 项目结构要点：

text

┌─────────────────────────────────────────────────────┐
│                 项目结构要点总结                     │
├─────────────────────────────────────────────────────┤
│                                                     │
│  📁 src/pages/     页面路由，文件即路由              │
│                                                     │
│  📁 src/components/ 可复用 UI 组件                   │
│                                                     │
│  📁 src/layouts/   页面布局模板                      │
│                                                     │
│  📁 src/content/   内容集合和 Markdown              │
│                                                     │
│  📁 public/        静态资源，直接复制               │
│                                                     │
│  📄 astro.config.mjs 主配置文件                     │
│                                                     │
│  📄 tsconfig.json  TypeScript 配置                  │
│                                                     │
└─────────────────────────────────────────────────────┘

下一步，让我们创建第一个项目，开始实际开发！