项目结构

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

¥Your new Astro project generated from the create astro CLI wizard already includes some files and folders. Others, you will create yourself and add to Astro’s existing file structure.

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

¥Here’s how an Astro project is organized, and some files you will find in your new project.

目录和文件

标题部分 目录和文件

¥Directories and Files

Astro 为你的项目利用有态度的文件夹布局。每个 Astro 项目根目录应包含以下目录和文件：

¥Astro leverages an opinionated folder layout for your project. Every Astro project root should include the following directories and files:

• src/* - 你的项目源代码（组件、页面、样式、图片等）

• public/* - 你的非代码、未处理的资源（字体、图标等）

• package.json - 项目清单。

• astro.config.mjs - Astro 配置文件。（受到推崇的）

• tsconfig.json - TypeScript 配置文件。（受到推崇的）

示例项目树

标题部分 示例项目树

¥Example Project Tree

常见的 Astro 项目目录可能如下所示：

¥A common Astro project directory might look like this:

• 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/

src/ 文件夹是大部分项目源代码所在的位置。这包括：

¥The src/ folder is where most of your project source code lives. This includes:

• 页面

• 布局

• Astro 组件

• UI 框架组件（React 等）

• 样式（CSS、Sass）

• Markdown

• Astro 要优化和处理的图片

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

¥Astro processes, optimizes, and bundles your src/ files to create the final website that is shipped to the browser. Unlike the static public/ directory, your src/ files are built and handled for you by Astro.

有些文件（如 Astro 组件）甚至不会按写入方式发送到浏览器，而是渲染为静态 HTML。其他文件（如 CSS）会发送到浏览器，但可能会进行优化或与其他 CSS 文件打包在一起以提高性能。

¥Some files (like Astro components) are not even sent to the browser as written but are instead rendered to static HTML. Other files (like CSS) are sent to the browser but may be optimized or bundled with other CSS files for performance.

Tip

While this guide describes some popular conventions used in the Astro community, the only directory reserved by Astro is src/pages/. You are free to rename and reorganize any other directories in a way that works best for you.

src/pages

标题部分 src/pages

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

¥Pages routes are created for your site by adding supported file types to this directory.

Caution

src/pages is a required sub-directory in your Astro project. Without it, your site will have no pages or routes!

src/components

标题部分 src/components

组件是 HTML 页面的可重复使用代码单元。这些可能是 Astro 组件 或 UI 框架组件，例如 React 或 Vue。通常在此文件夹中将所有项目组件分组和组织在一起。

¥Components are reusable units of code for your HTML pages. These could be Astro components, or UI framework components like React or Vue. It is common to group and organize all of your project components together in this folder.

这是 Astro 项目中的常见约定，但不是必需的。你可以随意组织你的组件！

¥This is a common convention in Astro projects, but it is not required. Feel free to organize your components however you like!

src/layouts

标题部分 src/layouts

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

¥Layouts are Astro components that define the UI structure shared by one or more pages.

就像 src/components 一样，该目录是通用约定，但不是必需的。

¥Just like src/components, this directory is a common convention but not required.

src/styles

标题部分 src/styles

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

¥It is a common convention to store your CSS or Sass files in a src/styles directory, but this is not required. As long as your styles live somewhere in the src/ directory and are imported correctly, Astro will handle and optimize them.

public/

标题部分 public/

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

¥The public/ directory is for files and assets in your project that do not need to be processed during Astro’s build process. The files in this folder will be copied into the build folder untouched, and then your site will be built.

此行为使 public/ 成为不需要任何处理的常见资源的理想选择，例如某些图片和字体，或特殊文件，例如 robots.txt 和 manifest.webmanifest。

¥This behavior makes public/ ideal for common assets that do not require any processing, like some images and fonts, or special files such as robots.txt and manifest.webmanifest.

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

¥You can place CSS and JavaScript in your public/ directory, but be aware that those files will not be bundled or optimized in your final build.

Tip

As a general rule, any CSS or JavaScript that you write yourself should live in your src/ directory.

package.json

标题部分 package.json

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

¥This is a file used by JavaScript package managers to manage your dependencies. It also defines the scripts that are commonly used to run Astro (ex: npm run dev, npm run build).

你可以在 package.json 中指定 两种依赖：dependencies 和 devDependencies。在大多数情况下，它们的工作原理是相同的：Astro 在构建时需要所有依赖，并且你的包管理器将安装这两个依赖。我们建议将所有依赖放在 dependencies 中启动，并且仅在你发现特定需要时才使用 devDependencies。

¥There are two kinds of dependencies you can specify in a package.json: dependencies and devDependencies. In most cases, these work the same: Astro needs all dependencies at build time, and your package manager will install both. We recommend putting all of your dependencies in dependencies to start, and only use devDependencies if you find a specific need to do so.

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

¥For help creating a new package.json file for your project, check out the manual setup instructions.

astro.config.mjs

标题部分 astro.config.mjs

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

¥This file is generated in every starter template and includes configuration options for your Astro project. Here you can specify integrations to use, build options, server options, and more.

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

¥Astro supports several file formats for its JavaScript configuration file: astro.config.js, astro.config.mjs, astro.config.cjs and astro.config.ts. We recommend using .mjs in most cases or .ts if you want to write TypeScript in your config file.

TypeScript 配置文件加载使用 tsm 处理，并将尊重你项目的 tsconfig 选项。

¥TypeScript config file loading is handled using tsm and will respect your project’s tsconfig options.

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

¥See the configuration reference for complete details.

tsconfig.json

标题部分 tsconfig.json

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

¥This file is generated in every starter template and includes TypeScript configuration options for your Astro project. Some features (like npm package imports) aren’t fully supported in the editor without a tsconfig.json file.

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

¥See the TypeScript Guide for details on setting configurations.