Astro 建站实战

一套基于 Astro v7 官方文档的中文实战教程：从「为什么是 Astro」出发，把文件路由、组件与布局、样式体系、内容集合、Markdown 渲染管线、交互岛屿、SEO 分发、构建部署逐一过一遍，最终长成一个能上线、能搜索、能分发的完整博客。

你正在看的这个网站，就是用 Astro 写的。 所以每一章除了讲文档概念，还有一节「对照本站」：把刚学的知识点映射到这个博客的真实源码上——你能看到每一个 API 在生产代码里的样子，包括我们踩过的坑。

这份教程怎么读

• 每章一个主题，按顺序读最好，但每章也自成一体，可以按需跳读。
• 每章固定的结构：学习目标 → 概念 → 动手实践 → 踩坑提示 → 对照本站（真实文件路径）→ 练习 → 遗留问题（引出下一章）。
• 所有示例代码都基于 Astro v7，与官方文档（docs.astro.build）同步。

章节目录

环境准备

# Node 22.19+ 或 24+（Astro v7 的要求）
node -v

# 创建第一个项目（选 Empty 模板即可跟着做）
npm create astro@latest

常用命令只有三个：

npm run dev      # 开发服务器 http://localhost:4321
npm run build    # 构建到 dist/
npm run preview  # 本地预览构建产物

前置知识

• HTML / CSS / 现代 JavaScript（模块、async/await、模板字符串）
• 不需要任何框架经验——Astro 组件比 React 组件更接近 HTML
• 需要一点 TypeScript 基础（本站与示例都用 TS，但可以当成「带类型的 JS」读）

约定

• 「对照本站」里的文件路径均指本博客仓库的相对路径，可直接在仓库里搜索定位。
• 示例代码力求可直接运行；与官方文档冲突时，以 docs.astro.build 为准并欢迎指正。