Astro 主题开发：从写网站到做主题

写过 Astro 网站之后，下一步自然是：能不能把我这套设计复用出去，让别人也用上？这就是主题开发——它和建站的区别不在技术难度，而在约束的转换：网站里你可以随手写死的东西（标题、导航、颜色），在主题里都必须收敛成配置项或内容约定，因为用主题的人和你不是一个人。

这个系列以官方文档为基础，带你把“一个能跑的博客”重构成“一个可分发的 Astro 主题”。一个现成的对照物就在眼前：本站就是 astro-cactus 主题 v8.3.0 的 fork——一个把站点配置、内容 schema、布局分层都收敛过的成熟主题，每个环节我们都会回头看看它是怎么做的。

内容依据 Astro 官方文档整理（组件、布局、样式、发布等页面），代码示例在其基础上改编，每章开头给出对应文档链接。

主题的两种形态

形态	使用方式	适合
模板仓库（GitHub Template）	用户点 “Use this template” 或 clone 后自己改代码	设计感强、深度定制的博客主题
npm 组件包	npm install 后按需引入组件/集成	复用某个部件（组件、适配器、加载器）

两个形态不互斥：astro-cactus 本质是模板仓库形态，但同样的代码加上 package.json 的 exports 就能变成 npm 包。第 7 章会展开两条路线。

章节导航

章节	内容	官方对应
第 1 章：主题的骨架	项目结构、目录分层、“会变的东西”收敛原则	项目结构
第 2 章：组件与 Props	组件语法、Props 接口、class 传递	Astro 组件
第 3 章：布局与插槽	BaseLayout 模式、slot 回退、嵌套布局	布局
第 4 章：样式与主题化	scoped 样式、全局样式边界、CSS 变量与暗色模式	样式与 CSS
第 5 章：为内容设计 schema	内容集合即契约：主题作者的 frontmatter 设计	内容集合
第 6 章：主题配置文件	site.config 模式：让用户改一个文件就能换脸	—（实践章）
第 7 章：分发主题	模板仓库 vs npm 包、workspaces、发布流程	发布到 npm
附录：主题开发检查清单	七个维度的自查清单 + 文档索引	—

学习路线建议

• 已读过本站《Astro 建站实战》系列：路由、内容集合基础、部署在那边讲过，本系列不重复，直接从“主题化改造”切入。
• 没读过也行：跟着官方 Blog 教程先建一个最小博客，再从第 1 章开始做主题化改造，效果一样。

遗留问题

• 主题的国际化（i18n）与多语言路由，超出本系列范围，官方有独立指南。
• 表单、搜索等需要服务端的交互，静态主题只覆盖前端形态。