项目结构与核心文件

用脚手架生成项目后，你会得到一个文件夹。里面一堆东西，新手容易懵：哪些是代码？哪些是配置？哪个能乱动、哪个别碰？

这一章就把这个「新家」逛一遍。记住 Astro 的目录是「约定优于配置」的——它希望你按它的规矩放文件，这样很多功能才自动生效。

先看整体长什么样

一个常见的 Astro 项目，目录大概是这样：

public/
  robots.txt
  favicon.svg
  my-cv.pdf
src/
  blog/
    post1.md
    post2.md
    post3.md
  components/
    Header.astro
    Button.jsx
  images/
    image1.jpg
    image2.jpg
    image3.jpg
  layouts/
    PostLayout.astro
  pages/
    posts/
      [post].astro
    about.astro
    index.astro
    rss.xml.js
  styles/
    global.css
  content.config.ts
astro.config.mjs
package.json
tsconfig.json

别慌，下面一块块拆。

src/：你的源代码老家

src/ 是绝大多数源码待的地方。组件、页面、样式、图片、Markdown，都归它管。你可以把它理解成「工地」：原材料都堆在这，Astro 这个「包工头」负责加工。

Astro 会对 src/ 里的文件做处理、优化、打包，最后才送到浏览器。比如 Astro 组件，写的时候是 .astro 文件，构建时会被渲染成静态 HTML；CSS 也可能被合并、压缩。正因为要加工，放这里的文件别指望「原样出现在成品里」——那是 public/ 的活。

src/pages：页面和路由

src/pages/ 是特殊目录——里面每放一个支持的文件，就自动变成一个网址。

• index.astro → 网站首页（/）。
• about.astro → /about 页面。
• posts/[post].astro → 带参数的动态路由。
• rss.xml.js → 一个输出 RSS 的端点（endpoint）。

这种「文件即路由」的设定，让你不用手写路由表，加页面就是加文件。

src/components：可复用组件

组件（component）是可重复使用的 HTML 代码片段。它们可以是 Astro 组件（Header.astro），也可以是 React、Vue 这类框架组件（Button.jsx）。

把导航栏、按钮、卡片这类反复出现的东西做成组件，页面里直接引用，省得到处复制粘贴。Astro 项目普遍把组件放这个文件夹，但它不是强制的。

src/layouts：布局

布局（layout）也是一种 Astro 组件，专门定义「多个页面共用的外壳」，比如统一的页头、页脚、整体排版。

博客常有一个 PostLayout.astro，所有文章页面都套它，保证样式一致。和 components 一样，这个目录是约定俗成的，不强制。

src/styles：样式

习惯上把 CSS 或 Sass 文件放 src/styles/，比如 global.css 做全局样式。只要样式在 src/ 内且被正确引入，放哪都行，Astro 会帮你优化。

src/images 与内容文件

图片如果希望 Astro 帮你优化、处理，就放 src/ 内（比如 src/images/）。Markdown 文章则常按主题归类，比如 src/blog/ 下放 post1.md 这类内容文件。

content.config.ts：内容集合的配置

注意 src/content.config.ts 这个文件。它是内容集合（content collections）的配置入口，用来定义你的内容「长什么样、该有哪些字段、怎么校验」。

public/：原样保留的静态资源

public/ 放那些「不需要 Astro 加工」的文件。里面的东西在构建时会被原封不动地拷进成品目录。

适合放这里的：

• 字体、图标（favicon.svg）。
• robots.txt、manifest.webmanifest 这类特殊文件。
• 不想被处理的现成图片、PDF（my-cv.pdf）。

你也能把 CSS、JavaScript 扔进 public/，但要清楚：它们不会被打包或优化，直接原样发布。一般没必要这么做。

package.json：项目清单

package.json 是 JavaScript 项目通用的「说明书」，包管理器靠它管理依赖。它也定义了常用脚本，比如 npm run dev、npm run build 这些命令就是在这里登记的。

依赖分两种：dependencies（运行需要）和 devDependencies（开发时需要）。Astro 构建时两者都要用，官方建议起步阶段先把依赖都放 dependencies，真有需要再细分。

astro.config.mjs：Astro 配置

astro.config.mjs 是每个起始模板都会生成的项目配置文件。在这里你能指定要用的集成（integration）、构建选项、服务器选项等。

Astro 支持几种配置文件格式：astro.config.js、.mjs、.ts。官方推荐多数情况用 .mjs；想在配置里写 TypeScript 就用 .ts。

示例里可能长这样（仅示意结构）：

import { defineConfig } from 'astro/config';

// 在这里引入集成、设置输出模式等
export default defineConfig({
  // integrations: [/* ... */],
});

tsconfig.json：TypeScript 配置

tsconfig.json 也是模板自带的，管 Astro 项目的 TypeScript 设置。有些功能（比如导入 npm 包）如果没有它，编辑器里支持不全。想深入配置，可查 Astro 的 TypeScript 指南。

这些文件是怎么串起来的

单独看每个文件也许还抽象。串一下完整流程就清楚了：

1. 你写页面放 src/pages/，写组件放 src/components/，公共外壳放 src/layouts/。
2. 页面用 import 把组件、布局、样式拉进来，组合成完整网页。
3. 内容文章放 src/blog/ 这类目录，由 src/content.config.ts 定义结构、统一管理。
4. 不加工的资源丢 public/，Astro 原样带走。
5. 构建时（npm run build），Astro 把 src/ 全处理一遍，和 public/ 合并，产出 dist/。
6. 整个过程受 astro.config.mjs、tsconfig.json、package.json 三个配置文件约束。

package.json 里的脚本长啥样

前面说 npm run dev、npm run build 是在 package.json 里登记的。典型的脚本长这样：

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "check": "astro check",
    "astro": "astro"
  }
}

dev 起本地预览，build 出成品，preview 在本地模拟「构建后的线上效果」，check 做类型与错误检查。你敲 npm run dev 时，npm 实际去跑了 astro dev 这条命令。想加自定义脚本，照着加一行就行。

还有几个你可能好奇的文件

除了上面几个主要的，项目里偶尔还会碰到这些：

• src/env.d.ts：Astro 自动生成的类型声明入口。它用一行 /// <reference path="../.astro/types.d.ts" /> 把 Astro 的类型注入编辑器，让你写代码时有提示。一般不用手改，留着就好。
• .gitignore：告诉 git 哪些文件「别提交」。node_modules/、dist/ 这类自动生成、体积又大的目录默认在里面。
• README.md：项目说明文件，记使用、部署的备忘，纯给人看的，Astro 不会处理它。

记住一条省心原则：node_modules/ 是装依赖的地方，可重建、别提交；dist/ 是构建产物，每次 build 都会重新生成，也别提交。 它们都能靠 .gitignore 自动避开。

小结

这一章把项目「房间布局」走完了：

1. src/ 是源码老家，Astro 会加工它；src/pages 决定路由，components 放组件，layouts 放布局，styles 放样式。
2. public/ 放不用加工的静态资源，原样拷贝。
3. package.json 管依赖和脚本；astro.config.mjs 管 Astro 配置；tsconfig.json 管 TypeScript。
4. 内容集合配置在 src/content.config.ts（v5+ 新写法，旧 src/content/config.ts 别再用）。

到这儿，前五章把「认识 Astro → 为什么快 → 适不适合 → 怎么装 → 项目长啥样」这条入门线走通了。接下来就可以深入组件、页面、布局这些核心写法了。