项目结构

通过 create astro CLI 向导生成的新 Astro 项目已经包含了一些文件和文件夹。其他的，你将自己创建并添加到 Astro 现有的文件结构中。

下面是 Astro 项目的组织方式，以及你将在新项目中找到的一些文件。

目录和文件

Astro 为你的项目采用了一种约定优于配置的文件夹布局。每个 Astro 项目的根目录都应包含以下目录和文件

• src/* - 你的项目源代码（组件、页面、样式、图片等）。
• public/* - 你的非代码、未经处理的静态资源（字体、图标等）。
• package.json - 一个项目清单文件。
• astro.config.mjs - 一个 Astro 配置文件。（推荐）
• tsconfig.json - 一个 TypeScript 配置文件。（推荐）

项目树示例

一个常见的 Astro 项目目录可能看起来像这样

• Directorypublic/

  • robots.txt
  • favicon.svg
  • my-cv.pdf
• Directorysrc/

  • Directoryblog/

    • post1.md
    • post2.md
    • post3.md
  • Directorycomponents/

    • Header.astro
    • Button.jsx
  • Directoryimages/

    • image1.jpg
    • image2.jpg
    • image3.jpg
  • Directorylayouts/

    • PostLayout.astro
  • Directorypages/

    • Directoryposts/

      • [post].astro
    • about.astro
    • index.astro
    • rss.xml.js
  • Directorystyles/

    • global.css
  • content.config.ts
• astro.config.mjs
• package.json
• tsconfig.json

src/

src/ 文件夹是你大部分项目源代码的存放位置。这包括

• 页面
• 布局
• Astro 组件
• UI 框架组件（React 等）
• 样式（CSS, Sass）
• Markdown
• 由 Astro 优化和处理的图像

Astro 会处理、优化和打包你的 src/ 文件，以创建最终交付给浏览器的网站。与静态的 public/ 目录不同，你的 src/ 文件由 Astro 为你构建和处理。

有些文件（如 Astro 组件）甚至不会按原样发送到浏览器，而是被渲染成静态 HTML。其他文件（如 CSS）会被发送到浏览器，但可能会被优化或与其他 CSS 文件捆绑在一起以提高性能。

提示

虽然本指南描述了 Astro 社区中使用的一些流行约定，但 Astro 唯一保留的目录是 src/pages/。你可以自由地以最适合你的方式重命名和重组任何其他目录。

src/pages

通过将支持的文件类型添加到此目录，可以为你的网站创建页面路由。

注意

src/pages 是你的 Astro 项目中一个必需的子目录。没有它，你的网站将没有页面或路由！

src/components

组件是用于 HTML 页面的可复用代码单元。这些可以是 Astro 组件，也可以是 UI 框架组件，如 React 或 Vue。将项目的所有组件都分组整理到这个文件夹中是一种常见的做法。

这是 Astro 项目中的一个常见约定，但不是必需的。你可以随心所欲地组织你的组件！

src/layouts

布局是 Astro 组件，用于定义一个或多个页面共享的 UI 结构。

就像 src/components 一样，这个目录是一个常见的约定，但不是必需的。

src/styles

将 CSS 或 Sass 文件存储在 src/styles 目录中是一种常见的约定，但不是必需的。只要你的样式文件位于 src/ 目录中的任何位置并被正确导入，Astro 就会处理和优化它们。

public/

public/ 目录用于存放项目中在 Astro 构建过程中不需要处理的文件和资源。此文件夹中的文件将被原封不动地复制到构建文件夹中，然后你的网站将被构建。

这种行为使得 public/ 目录非常适合存放不需要任何处理的常见资源，例如一些图像和字体，或特殊文件，如 robots.txt 和 manifest.webmanifest。

你可以将 CSS 和 JavaScript 放在 public/ 目录中，但请注意，这些文件在最终构建中不会被打包或优化。

提示

一般来说，任何你自己编写的 CSS 或 JavaScript 都应该放在 src/ 目录中。

package.json

这是一个被 JavaScript 包管理器用来管理你的依赖项的文件。它还定义了通常用于运行 Astro 的脚本（例如：npm run dev, npm run build）。

在 package.json 文件中，你可以指定两种依赖：dependencies 和 devDependencies。在大多数情况下，它们的作用是相同的：Astro 在构建时需要所有依赖项，你的包管理器会同时安装这两种依赖。我们建议开始时将所有依赖项都放在 dependencies 中，只有在发现有特定需要时才使用 devDependencies。

有关为你的项目创建新的 package.json 文件的帮助，请查看手动设置说明。

astro.config.mjs

该文件在每个入门模板中都会生成，并包含你的 Astro 项目的配置选项。在这里，你可以指定要使用的集成、构建选项、服务器选项等。

Astro 的 JavaScript 配置文件支持多种文件格式：astro.config.js、astro.config.mjs、astro.config.cjs 和 astro.config.ts。在大多数情况下，我们建议使用 .mjs，如果你想在配置文件中编写 TypeScript，则建议使用 .ts。

TypeScript 配置文件的加载由 tsm 处理，并将遵循你项目的 tsconfig 选项。

有关完整详细信息，请参阅配置参考。

tsconfig.json

该文件在每个入门模板中都会生成，并包含你的 Astro 项目的 TypeScript 配置选项。如果没有 tsconfig.json 文件，某些功能（如 npm 包导入）在编辑器中无法得到完全支持。

有关设置配置的详细信息，请参阅 TypeScript 指南。