ikoTheme 开发日志 #0：为什么我要自己写一套 Astro 主题

用 vhAstro 二开了大半年，我终于决定亲手写一套属于自己的 Astro 主题。这不是一时冲动——当第三次解决「上游更新与本地魔改的合并冲突」时，我就知道该换个思路了。

为什么不是继续改 vhAstro

vhAstro 是一套完成度很高的主题，视觉到现在我依然喜欢。但「二开」天生有一个结构性问题：你的每一处修改都是对上游的偏离。偏离越多，升级越痛，最后主题被锁死在某个旧版本。

• 项目展示是刚需：我需要的不只是「文章博客」，而是文章 + 项目集的组合门面
• 暗色模式是底线：开发者读者一半时间在暗处
• 类型安全的内容模型：frontmatter 写错字段应该在构建期报错，而不是渲染出空白页

造轮子的意义不在轮子本身，而在于你终于拥有一辆完全按自己路况调校的车。

我想要的主题长什么样

项目是一等公民

文章页之外，项目要有独立的集合与页面：状态徽章、技术栈、仓库与 Demo 链接。首页的瀑布流里，项目卡片与文章卡片同等露出。

性能是底线

目标是 Lighthouse 四项全 100：默认零客户端 JS、astro:assets 管理图片、字体走系统栈起步，交互岛屿按需注水。

内容迁移零成本

Markdown + frontmatter 的内容组织方式保持不变，从 Hexo / vhAstro 迁移只需要一个脚本批量改写 frontmatter。

技术方案速览

关注点	选型	理由
框架	Astro 5	内容集合 + 零默认 JS
样式	Tailwind CSS 4	原子化迭代快
搜索	Pagefind	构建期生成索引
评论	giscus	数据存 GitHub Discussions

下一步

• M1：仓库脚手架 + 内容集合 schema 定稿
• M2：七个页面全部落地
• M3：Pagefind 搜索、giscus 评论、RSS 全文输出
• M4：Lighthouse 全 100、双语 README、发布 v1.0

这个系列会随着开发持续更新——你正在读的，就是第一篇。