Astro 系列（二）：项目结构与开发约定

astroproject-structurefrontendconventions

Astro 入门与实战 系列导航

  1. （一）Astro 是什么，解决什么问题
  2. （二）项目结构与开发约定 ← 当前
  3. （三）Island 架构——为什么默认零 JavaScript
  4. （四）内容驱动还是应用驱动——Astro 的边界
  5. （五）SSR 还是 SSG，怎么选
  6. （六）集成生态——从官方到社区
  7. （七）能用 Astro 做什么——扩展玩法全景
  8. （八）View Transitions——让 MPA 拥有 SPA 体验
  9. （九）Middleware、API 端点与认证
  10. （十）第三方服务拼装——评论、搜索、分析
  11. （十一）框架对比（上）——全栈方向
  12. （十二）框架对比（下）——静态站点方向
# 项目结构与开发约定 ## 脚手架与初始化 ### create astro ### 模板选择 ### 手动配置 ## 目录结构 ### src/pages ### src/layouts ### src/components ### src/content ### public ### astro.config ## 文件路由 ### 静态路由 ### 动态路由 [slug] ### 多段路由 [...slug] ### 重定向 ## 布局系统 ### 页面布局 ### 插槽 slot ### 嵌套布局 ### 布局透传 props ## 内容集合 ### 类型安全 ### Schema 定义 ### 集合查询 ### frontmatter 约定 ## 约定优于配置 ### 零配置路由 ### 自动类型推导 ### 文件即约定

初始化：几秒钟启动一个项目

Astro 提供 CLI 脚手架，一行命令创建项目：

npm create astro@latest

交互式向导会问几个问题：项目名、是否使用 TypeScript、是否初始化 Git。完成后得到一个标准目录结构。

相比之下，Next.js 和 Nuxt 的初始化流程更重——需要选择路由方式、数据获取策略、CSS 方案等。Astro 的哲学是"先跑起来，再按需加"。

目录结构：每层有明确职责

my-astro-site/
├── src/
│   ├── pages/          # 路由页面，文件名 = URL
│   ├── layouts/        # 页面布局（壳）
│   ├── components/     # 可复用组件（.astro / .jsx / .vue）
│   ├── content/        # 内容集合（Markdown / MDX）
│   └── styles/         # 全局样式
├── public/             # 静态资源，直接复制到构建输出
├── astro.config.mjs    # 项目配置
└── package.json

这个结构与 Next.js 的 app/ 或 pages/ 目录相比，最大的区别是 content/ 是 Astro 的一等公民。它不是 src/ 的子目录，而是与 src/ 平级——体现"内容优先"的理念。

文件路由：路径即约定

Astro 使用基于文件系统的路由，与 Next.js、SvelteKit 一致：

  • src/pages/index.astro → /
  • src/pages/about.astro → /about
  • src/pages/blog/index.astro → /blog
  • src/pages/blog/[slug].astro → /blog/hello-world
  • src/pages/blog/[...slug].astro → /blog/2024/01/hello

不需要在代码里声明路由表。文件放在哪，URL 就在哪——这是"约定优于配置"的典型体现。

布局系统：页面壳的复用

Astro 的布局是特殊的 Astro 组件，通过 <slot /> 接收子页面内容：

  • 页面指定 layout，布局包裹页面
  • 布局可以嵌套（外层壳 > 内层壳 > 内容）
  • Props 从页面透传到布局（title、description 等）

这种模式比 React 的 children props 更直观，因为它是文本模板思维——布局就是 HTML 壳，内容是填充进去的。

内容集合：Markdown 的类型安全层

这是 Astro 区别于其他 SSG 的关键特性。在 src/content/config.ts 中定义 schema：

  • 每个集合有明确的 frontmatter 类型
  • 编辑器获得自动补全
  • 构建时类型校验，写错字段会报错

内容集合的查询 API 也设计得很自然——getCollection('blog') 返回所有文章，支持过滤、排序、分页。这让"从 Markdown 生成页面"这件事变得极其顺畅。

约定优于配置的思想

Astro 大量采用约定优于配置（Convention over Configuration）：

  • 文件位置决定路由，不需要声明
  • 文件类型决定处理方式（.astro → Astro 组件，.md → 内容条目）
  • 内容集合 schema 是唯一的"配置"，其余靠目录结构表达

这种设计降低了认知负担——你知道一个文件应该放哪，不是因为读了文档，而是因为"它就该在那里"。Ruby on Rails 把这一理念带火，Astro 把它带到了 SSG 世界。

延伸阅读

实操清单

  • 用 npm create astro@latest 创建一个测试项目
  • 浏览生成的项目目录，对照本文理解每个目录的职责
  • 在 src/pages/ 下新建一个 .astro 页面文件，观察 URL 变化
  • 阅读内容集合的官方文档，理解 schema 定义方式

created by:codex on deepseek v4 pro