Astro Basics 入门模板全解：项目结构、命令体系与模板初始化机制

2026-09-04 23:56:55作者：范垣楠Rhoda

Astro 官方仓库中的 examples/basics 目录既是「Basics 入门模板」的源码，也是 npm create astro 创建新项目时的默认模板。本文以 examples/basics/README.md 为主线，完整讲解该模板的安装方式、目录结构、核心文件写法与命令体系，并结合 create-astro 的模板处理源码深入说明「你 clone 下来的模板」和「仓库里的模板」之间的差异是如何产生的。读完后，你可以独立创建、阅读并修改一个可运行的 Astro 项目。

一、什么是 Basics 模板，如何安装

模板 README 的第一行就是安装命令：

npm create astro@latest -- --template basics

create-astro 是 Astro 官方的项目创建工具，--template basics 指定使用 examples/basics 作为项目骨架；
从源码看，basics 是内置的默认模板：在 packages/create-astro/src/actions/template.ts 中，当使用 --yes 跳过交互且未指定模板时，会执行 if (!ctx.template && ctx.yes) ctx.template = 'basics'；交互模式下模板选择列表也以 basics 为初始项，标注为 “A basic, helpful starter project (recommended)”，与 blog（博客）、starlight（文档站）、minimal（空模板）并列。

模板内 package.json 声明了运行环境要求，见 examples/basics/package.json：

{
  "name": "@example/basics",
  "type": "module",
  "engines": { "node": ">=22.12.0" },
  "dependencies": { "astro": "^7.2.10" }
}

也就是说，当前仓库中的 Basics 模板面向 Node.js 22.12 及以上版本、Astro 7.x 版本。"type": "module" 表示项目使用 ES Module，这也是 Astro 7 项目的标准形态。

二、项目结构：README 目录树逐层解读

README 给出的项目结构如下（原样继承自 README）：

/
├── public/
│   └── favicon.svg
├── src
│   ├── assets
│   │   └── astro.svg
│   ├── components
│   │   └── Welcome.astro
│   ├── layouts
│   │   └── Layout.astro
│   └── pages
│       └── index.astro
└── package.json

各目录的职责，结合仓库中的实际文件说明：

目录 / 文件	职责	仓库中实际内容
`public/`	静态资源目录，构建时原样拷贝，文件以根路径 `/` 访问	favicon.svg 与 favicon.ico，在 Layout.astro 的 `<head>` 中通过 `/favicon.svg`、`/favicon.ico` 引用
`src/assets/`	会被构建管线处理的资源。与 `public/` 不同，这里 import 的图片会由 Vite 处理（URL 可能带 hash、可查询参数）	astro.svg（Logo）与 background.svg（模糊背景图），在 Welcome.astro 中以 `import astroLogo from '../assets/astro.svg'` 的方式引入
`src/components/`	可复用组件目录	Welcome.astro
`src/layouts/`	全局布局组件	Layout.astro
`src/pages/`	路由目录，每个文件对应一个 URL 路由	index.astro 对应首页 `/`

注意仓库根目录的 examples/basics/tsconfig.json 和 examples/basics/astro.config.mjs 也是模板的一部分，前者为 IDE 提供类型检查基础，后者定义 Astro 配置。

三、核心文件源码详解

3.1 Layout.astro：全局 HTML 骨架与 `<slot />`

Layout.astro 提供了整站共用的 <html> 骨架：

<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width" />
        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
        <link rel="icon" href="/favicon.ico" />
        <meta name="generator" content={Astro.generator} />
        <title>Astro Basics</title>
    </head>
    <body>
        <slot />
    </body>
</html>

几个值得注意的点：

<slot /> 是布局组件的「内容出口」，页面组件放入 <Layout> 标签内的内容会被渲染到该位置；
Astro.generator 是框架内置的全局变量，会自动注入 astro 的生成器 <meta> 标签；
文件末尾的 <style> 没有 is:global 标记，属于 Astro 的默认 scoped 样式，只会作用于该组件自身标记的 html/body 选择器，不会污染子组件。

3.2 index.astro：页面如何组合组件

首页 index.astro 只有短短几行，却展示了 Astro 文件的两段式结构（frontmatter + 模板）：

---
import Welcome from '../components/Welcome.astro';
import Layout from '../layouts/Layout.astro';
---

<Layout>
    <Welcome />
</Layout>

--- 之间的 frontmatter 是 JS/TS 代码区，负责导入；
frontmatter 之外的部分编译为 HTML 模板；
文件顶部注释给出了「推倒重来」的官方建议：删除本文件内容以及 assets、components、layouts 三个目录即可从零开始。

3.3 Welcome.astro：资源引用、内联样式与框架特性

Welcome.astro 是模板中信息密度最高的文件，它示范了三个常用能力：

通过 import 引用构建资产。import background from '../assets/background.svg' 之后用 src={background.src} 渲染背景，并配合 fetchpriority="high" 提示浏览器优先加载：
```
<img id="background" src={background.src} alt="" fetchpriority="high" />
```
组件内 <style> 自动作用域。该组件约 180 行 CSS（响应式布局、渐变按钮、移动端媒体查询等）只作用于本组件，天然避免与页面其他组件的样式冲突。
原生 HTML 属性直接透传。如 <a>、<svg>、<img> 无需任何额外配置即可书写。

组件右下角还有一个「What's New in Astro 7.0?」信息卡片，文案提及 Rust 编译器等新特性，链接指向 Astro 7.0 发布博客——这也侧面印证了当前模板所处的 Astro 7.x 版本周期。

3.4 astro.config.mjs：最小配置

astro.config.mjs 只有 5 行：

// @ts-check
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});

Basics 模板刻意保持空配置 defineConfig({})，只保留 @ts-check 注释以获得配置文件的类型提示。后续要开启站点、集成中间件或框架集成时，都是在这个对象里扩展（例如 site、markdown、integrations 等键）。

四、命令体系：npm scripts 与 Astro CLI

README 的命令表原样继承如下，全部从项目根目录的终端执行：

命令	作用
`npm install`	安装依赖
`npm run dev`	在 `localhost:4321` 启动本地开发服务器
`npm run build`	将生产站点构建到 `./dist/`
`npm run preview`	本地预览构建产物，用于部署前检查
`npm run astro ...`	运行 CLI 命令，如 `astro add`、`astro check`
`npm run astro -- --help`	查看 Astro CLI 帮助

这些 npm 脚本的映射关系在 examples/basics/package.json 中可以一一对应：

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

即 npm run dev/build/preview 只是 astro 三个子命令的快捷方式，而 "astro": "astro" 脚本让你可以把任意子命令（astro add、astro check 等）以 npm run astro <args> 的形式透传。

五、从源码看模板初始化：仓库模板 ≠ 你下载的模板

直接浏览仓库中的 examples/basics/README.md 会发现 README 里有若干「仓库专属」内容，而你通过 create astro 创建的项目里看不到它们。这个差异由 packages/create-astro/src/actions/template.ts 在下载模板后自动处理，机制值得理解：

ASTRO:REMOVE 标记段会被整段删除。README 中的在线编辑器徽章（StackBlitz / CodeSandbox / Codespaces）被包裹在  …  之间。removeTemplateMarkerSections() 用正则 /[\s\S]*?/gi 匹配并清除这些段落（源码）。这些徽章只对「浏览仓库源码的人」有意义，对实际项目是噪音，所以下载时移除。
包管理器命令会被自动替换。processTemplateReadme() 会检测你选择的包管理器，若非 npm，则把 README 中的 npm run、npm 批量替换为对应命令（源码）。这就是为什么 pnpm/bun 用户拿到的模板说明里写的是 pnpm dev 而不是 npm run dev。
模板来源与 404 处理。getTemplateTarget() 把模板名解析为下载地址：basics 在 latest 引用下解析为 github:withastro/astro#examples/basics，即直接取本仓库的 examples/basics 子目录（源码）；下载失败且返回 404 时会抛出 Template <name> does not exist! 错误。
package.json 会被改写。copyTemplate() 会把模板的 name 改为你创建项目时指定的项目名，并删除 "private": true 字段（源码）——这解释了为什么仓库里是 @example/basics，而你的新项目会显示自己的名字。
可选的 AI 代理支持文件。若创建时启用 --ai 相关选项，工具会额外生成 AGENTS.md（并尝试为 CLAUDE.md 建立符号链接），内容包含 astro dev --background 后台运行方式等指引（源码）。

六、下一步：如何扩展 Basics 项目

模板 README 末尾提示 “Seasoned astronaut? Delete this file. Have fun!”，即熟悉之后可以删除 README 本身。结合仓库中同级模板，进阶路径是：

学习页面路由、组件、内容集合等主题时，可参考 README 指向的官方文档（examples/basics/README.md 中的 “Want to learn more?” 一节）；
需要博客结构时对比 examples/blog 模板；
需要文档站点时对比 starlight 模板（create-astro 中的 starlight 选项会解析到 Starlight 仓库的示例，见 getTemplateTarget() 的分支逻辑）；
想要完全空白的项目，使用 minimal 模板（对应本仓库 examples/minimal）。

修改 Basics 项目的最小路径是：在 src/pages/ 下新增页面文件即得到新路由；修改 Layout.astro 即修改全站骨架；调整 astro.config.mjs 即调整构建行为。三者覆盖了日常开发中绝大多数入口点。

七、小结

Basics 模板的定位：create astro 的默认（recommended）模板，仓库源码位于 examples/basics，安装命令为 npm create astro@latest -- --template basics；
五类核心文件：public/（静态资源）、src/assets/（构建资源）、src/components/（组件）、src/layouts/（布局）、src/pages/（路由），外加最小化的 astro.config.mjs；
四组命令：npm install / npm run dev（4321 端口）/ npm run build（输出到 ./dist/）/ npm run preview，均可在 package.json 的 scripts 中验证其映射；
模板与项目的差异：README 中 ASTRO:REMOVE 标记段、package.json 的 private 字段等是仓库形态特有，下载时由 create-astro 源码自动清理与改写。