Skip to content
Astro Astro

项目结构

从 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.

目录和文件

Section titled 目录和文件

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 配置文件。 （受到推崇的）

示例项目树

Section titled 示例项目树

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

英A common Astro project directory might look like this:

  • Directorypublic/
    • robots.txt
    • favicon.svg
    • social-image.png
  • Directorysrc/
    • Directorycomponents/
      • Header.astro
      • Button.jsx
    • Directorylayouts/
      • PostLayout.astro
    • Directorypages/
      • Directoryposts/
        • post1.md
        • post2.md
        • post3.md
      • index.astro
    • Directorystyles/
      • global.css
  • astro.config.mjs
  • package.json
  • tsconfig.json

src/

Section titled src/

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

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

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 提示 虽然本指南描述了 Astro 社区中使用的一些流行约定，但 Astro 保留的唯一目录是 src/pages/ 和 src/content/。 你可以以最适合你的方式自由重命名和重新组织任何其他目录。 :::

src/components

Section titled 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/content

Section titled src/content

保留 src/content/ 目录来存储 内容集合 和可选的集合配置文件。 此文件夹中不允许有其他文件。

英The src/content/ directory is reserved to store content collections and an optional collections configuration file. No other files are allowed inside this folder.

src/layouts

Section titled 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/pages

Section titled src/pages

页面 是一种特殊的组件，用于在你的网站上创建新页面。 页面可以是 Astro 组件，也可以是表示站点内容的某些页面的 Markdown 文件。

英Pages are a special kind of component used to create new pages on your site. A page can be an Astro component, or a Markdown file that represents some page of content for your site.

:::caution 提醒 src/pages 是 Astro 项目中的 required 子目录。 没有它，你的网站将没有页面或路由！ :::

src/styles

Section titled 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/

Section titled public/

public/ 目录用于存放在 Astro 构建过程中不需要处理的文件和资源。 这些文件将原封不动地复制到构建文件夹中。

英The public/ directory is for files and assets that do not need to be processed during Astro’s build process. These files will be copied into the build folder untouched.

此行为使 public/ 非常适合图片和字体等常见资源，或 robots.txt 和 manifest.webmanifest 等特殊文件。

英This behavior makes public/ ideal for common assets like 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 提示 作为一般规则，你自己编写的任何 CSS 或 JavaScript 都应位于 src/ 目录中。 :::

package.json

Section titled package.json

这是 JavaScript 包管理器用来管理依赖的文件。 它还定义了通常用于运行 Astro 的脚本（例如：npm start、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 start, 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

Section titled 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 指南。

英See the Configuring Astro Guide for details on setting configurations.

tsconfig.json

Section titled 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.