Astro 示例模板库实战指南：从 examples 目录到 create-astro 的底层实现

本文以 Astro 官方仓库中的 示例库说明文档 为主体，讲解如何用一条命令把 examples/ 目录下的任意示例模板拉取到本地运行；并结合 create-astro 源码 深入剖析模板解析、第三方模板支持、README 后处理与依赖安装的完整机制，帮助你在理解原理的基础上更高效地选型和启动 Astro 项目。

用一条命令运行任意官方示例

在 examples/ 目录下的官方文档 examples/README.md 中，给出的核心用法是在空目录中执行：

npm create astro@latest -- --template [EXAMPLE_NAME]

这里的 [EXAMPLE_NAME] 就是 examples/ 目录下的子目录名。也就是说，你不需要手动 git clone 整个仓库，create-astro 会直接把对应示例下载到你当前的工作目录。当前仓库中的 examples/ 目录包含以下 23 个官方示例，均可作为模板名直接使用：

模板名	用途（来自各示例 README 首段说明）
basics	官方推荐的基础起步项目（interactive 模式的默认推荐项）
blog	内容集合驱动的博客模板
hackernews	Hackernews 风格的资讯站
portfolio	个人作品集模板
starlog	发布日志（Release Notes）主题
ssr	服务端渲染示例（Node adapter + Svelte）
minimal	最小化（近乎空）模板
advanced-routing	高级路由示例（含 actions）
framework-react / framework-vue / framework-svelte / framework-preact / framework-solid / framework-alpine	各框架组件集成示例
framework-multiple	"Kitchen Sink"：同时使用多种框架
with-mdx / with-markdoc	MDX 与实验性 Markdoc 集成示例
with-tailwindcss	Tailwind CSS 集成示例
with-nanostores	Nano Stores 状态管理示例
with-vitest / container-with-vitest	Vitest 测试示例（含 Container API）
component	组件包模板（可发布到 NPM）
integration	Astro 集成包模板
toolbar-app	开发工具栏（Toolbar）应用模板

这些示例在仓库中都是真实可构建的项目，每个目录下都有自己的 astro.config.mjs、package.json 和 README，你可以直接在仓库中查看任何示例的完整实现。

模板解析机制：create-astro 如何找到你的模板

npm create astro@latest -- --template xxx 背后的执行逻辑位于 packages/create-astro/src/index.ts，它按 verify → intro → projectName → template → dependencies → git 的顺序执行各步骤，其中模板下载由 template.ts 完成。

三种模板来源的路由规则

getTemplateTarget() 函数决定了模板的最终下载地址，其路由规则有三层：

1. Starlight 模板：starlight 或 starlight/<starter> 会被重定向到 Starlight 仓库对应的 examples/<starter> 路径（默认 basics）；
2. 第三方模板：模板名中包含路径分隔符 / 时（见下文的 isThirdPartyTemplate()），视为第三方模板，按原样透传；
3. 官方 Astro 模板：当 ref 为 latest（默认）时，目标被解析为 withastro/astro#examples/<模板名> 这一专门分支——源码注释解释了这个优化：latest 分支让下载器只取该分支，避免下载整个仓库再拷贝子目录，从而显著加快下载速度。

交互式选择与默认值

如果未提供 --template 参数，template() 会弹出交互式选择，候选项为 basics（标注 "recommended"）、blog、starlight、minimal；配合 --yes 时直接采用 basics。

下载后的自动化后处理

copyTemplate() 在下载完成后的后处理值得注意：

• README 模板标记剥离：官方示例的 README 中普遍包含 <!-- ASTRO:REMOVE:START --> ... <!-- ASTRO:REMOVE:END --> 标记区块（例如 basics 示例的 README 中包裹 StackBlitz/CodeSandbox 徽章和预览图的段落）。下载后 removeTemplateMarkerSections() 会把这些区块从你的 README 中删除——因为这些在线编辑器徽章只对"打开官方仓库分支"有意义；同时 processTemplateReadme() 会把 README 中的 npm 字样替换为你实际使用的包管理器；
• package.json 改名：通过 FILES_TO_UPDATE 把 name 改为你输入的项目名，并删除 private 字段（官方示例的 package.json 都带有 "private": true 和 @example/xxx 名称，如 examples/basics/package.json）；
• 删除仓库专用文件：CHANGELOG.md、.codesandbox 等仅在在线编辑器场景需要的文件会被移除；
• AI 代理文件生成：启用时会在项目根生成 AGENTS.md（并尝试创建 CLAUDE.md 符号链接），内容见 generateAgentsMd()，可通过 --no-ai 跳过。

以 basics 示例为例：模板包含什么

拉取 basics 模板后得到的标准目录结构（摘自 examples/basics/README.md）：

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

对应目录在仓库中为 examples/basics/。各脚本命令（官方 README 命令表，完整保留）：

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

其 astro.config.mjs 只有一行 export default defineConfig({})——这正是"最小可运行配置"的样子，任何扩展（适配器、集成、i18n 等）都是在这个空配置上叠加。

进阶示例：ssr 模板的构建与运行方式

ssr 示例 展示了服务端渲染场景。根据其 README，该示例使用 @astrojs/node adapter 配合 output: "server" 按需渲染页面，并从 src/pages/api/ 暴露 API 路由，同时集成 @astrojs/svelte 渲染客户端组件。其命令表在 basics 基础上多出一行：

命令	作用
npm run server	从 ./dist/server/ 运行构建好的 Node 服务器

这说明 SSR 模板的产物是可直接部署的 Node 服务器，而非纯静态文件，适合需要 API 路由与动态渲染的项目选型参考。

社区模板：第三方仓库与嵌套路径支持

除了官方 examples/ 目录，create-astro 完整支持社区模板。examples/README.md 中给出的三种形式：

# 使用社区仓库中的模板
npm create astro@latest -- --template [GITHUB_USER]/[REPO_NAME]

# 支持仓库内嵌套路径，定位到子目录中的示例
npm create astro@latest -- --template [GITHUB_USER]/[REPO_NAME]/path/to/example

从源码看，判定逻辑很直接：isThirdPartyTemplate() 只要发现模板名包含 / 且不是内置的 starlight 前缀，就按第三方模板处理，并原样传给下载器（giget 支持 github:user/repo[/path] 形式的目标）。

安全提示：dependencies.ts 中有一条明确警告——第三方模板在安装依赖时可能执行生命周期脚本（postinstall 等）。如果你不完全信任该模板，应使用 --no-install 跳过自动安装，手动审查后再执行包管理器的 install。

CLI 参数速查

以下是 help.ts 中声明的全部可用参数：

参数	说明
--help (-h)	查看全部可用参数
--template <name>	指定模板名
--install / --no-install	是否安装依赖
--add <integrations>	额外添加集成（如 --add react）
--git / --no-git	是否初始化 git 仓库
--no-ai	跳过创建 AI 代理文件
--yes (-y)	跳过所有交互提示，采用默认值
--no (-n)	跳过所有交互提示，拒绝默认值
--dry-run	只走流程不实际执行
--skip-houston	跳过启动动画
--ref	指定 Astro 分支（默认 latest）
--fancy	在 Windows 上启用完整 Unicode 支持

其中 --ref 与模板解析直接相关：非 latest 的 ref 会被拼到路径末尾（examples/<模板名>#<ref>），用于测试 Astro 特定分支上的示例。

依赖安装的包管理器适配细节

执行 npm create astro@latest 时，dependencies 步骤 会针对三种主流包管理器做特殊预处理，这些细节解释了为什么"一条命令"在不同包管理器下都能顺利跑通：

• pnpm：ensurePnpmBuildsAllowed() 会在 pnpm-workspace.yaml 中预写 allowBuilds: { esbuild: true, sharp: true }，规避 pnpm 默认 strictDepBuilds 对含构建脚本依赖的拦截；
• npm：ensureNpmScriptsAllowed() 会在 package.json 写入 allowScripts: { esbuild: true }，对应 npm 新版本对未批准安装脚本的告警/失败机制（这也是 examples/basics/package.json 中 allowScripts 字段存在的原因）；
• yarn：ensureYarnLock() 会先写入一个空 yarn.lock，规避 Yarn Berry（PnP）在无 lock 文件时报错的问题。

如果指定了 --add，安装完成后还会以 npx astro add <integrations> -y（npm）或 <pm> dlx astro add ... 的形式调用 astroAdd() 追加集成，且每个集成名都会经过包名合法性校验以防命令注入。

小结

examples/ 示例库 + create-astro 的模板机制，构成了 Astro 项目起步的完整闭环：--template 参数在 getTemplateTarget() 中按"Starlight → 第三方 → 官方分支"三级路由解析，下载后自动完成 README 净化、package.json 改名与包管理器适配，最终你得到一个可直接 npm run dev 的独立项目。对于想深入某个具体场景（内容集合、SSR、多框架、测试等）的读者，直接从 examples/ 目录挑选对应示例作为起点，是阅读源码之前最快的实践路径。