Ethan · ikoobee.com

ikoTheme 开发日志 #1：灯箱、公式与丝滑的页面过渡

Fri, 04 Sep 2026 00:00:00 GMT

v1.0 发布之后，我对着同类主题的功能清单做了一次逐项对比，最后圈出四个「低成本、高感知」的候选：图片灯箱、LaTeX 公式、页面过渡、侧边栏配置化。v1.1 把它们全部落地了，这篇记录一下取舍。

灯箱：原生 `<dialog>` 就够了

市面上的灯箱方案几乎都要引库。但 2026 年了，原生 <dialog> 自带焦点管理、Esc 关闭和 ::backdrop，配上三十行样式就是一个完整灯箱：

<dialog id="lightbox">
  <img id="lightboxImg" alt="" />
  <button id="lightboxClose" aria-label="关闭预览">✕</button>
</dialog>

点击文章图片时把 currentSrc 灌进弹窗、showModal() 一气呵成。图注直接取 alt 文本，无障碍和懒加载都是白送的。

公式：构建期渲染，客户端零成本

数学公式走 remark-math + rehype-katex，在构建期就渲染成 HTML 和 CSS，浏览器不跑一行 JS。比如模拟退火的接受概率：

$$ P(\text{accept}) = \exp\left(-\frac{\Delta E}{T}\right) $$

行内公式像 $\alpha = 0.95$ 这样写就行。踩过一个坑：$$公式$$ 写在同一行不会被识别为块级公式，独立成段才是正确姿势——这个约定已经写进 README。

页面过渡：最难的不是动画

接入 Astro 的 ClientRouter 只要一行，难的是让全站脚本在「换页不刷新」的世界里继续正常工作。重构原则很简单：

常驻行为（主题切换、滚动监听）绑定在 document 上，用事件委托，永远只绑一次；
页面级初始化（筛选、打字机、评论区懒加载）全部挂到 astro:page-load，每次换页重新执行；
搜索弹窗和灯箱用 transition:persist 跨页保活，状态不丢。

Hero 的粒子动画加了 isConnected 自检，页面切走后循环自动终止，不留僵尸 rAF。

结果

本地 Lighthouse 实测：首页性能 99 / 无障碍 92 / 最佳实践 100 / SEO 100，文章页性能满分。四项全过 CI 门禁的 90 分线，「零默认客户端 JS」的底线也守住了。

下一个大项是 i18n（zh/en），体量够单独发一个版本。在那之前，先用这套主题把文章写起来。

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

Wed, 02 Sep 2026 00:00:00 GMT

用 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

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

Astro 5 内容集合实战：从 Markdown 到类型安全的站点

Fri, 28 Aug 2026 00:00:00 GMT

内容集合（Content Collections）是 Astro 最被低估的能力：它让你的 Markdown 不再是「一堆字符串」，而是一组构建期校验过的数据。

定义集合与 schema

在 src/content.config.ts 里用 zod 声明每个集合的形状：

import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";

const posts = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/content/posts" }),
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    category: z.enum(["Code", "Tutorial", "Essay", "Daily"]),
    tags: z.array(z.string()).default([]),
  }),
});

写错字段名或日期格式，构建直接失败并指出是哪个文件——这在二开主题时代是想都不敢想的体验。

类型推导直达页面

---
import { getCollection } from "astro:content";
const posts = await getCollection("posts", (p) => !p.data.draft);
---
{posts.map((p) => <h2>{p.data.title}</h2>)}

编辑器里 p.data. 的每一次补全，都来自你的 schema。

踩过的坑

z.coerce.date() 接受字符串日期，但时区按 UTC 解析，展示时注意格式化
glob 加载器的 base 是相对项目根目录，不是相对配置文件
frontmatter-only 的 .md（没有正文）也是合法条目，entry.body 为 undefined

小结

内容集合换来的不是「又一个 API」，而是整条内容流水线的类型安全。主题作者把 schema 定义好，使用者写内容时就被保护了。

爬山算法 × 模拟退火：教室排座工具的寻优之路

Sat, 15 Aug 2026 00:00:00 GMT

这个项目的起因是当班主任的朋友一句吐槽：「每次换座位都要权衡四十多个学生的关系，比写代码难多了」。我说：那就交给代码。

把愿望翻译成目标函数

寻优算法的第一步不是选算法，而是定义「好」。我们把老师的直觉拆成可计算的规则，每条规则一个权重：

function score(seats, rules) {
  let total = 0;
  for (const [a, b, w] of rules.pairs) {
    if (isNeighbor(seats, a, b)) total += w; // 想同桌 +w
  }
  return total - penalty(seats, rules.blocks);
}

爬山与退火

先试了最朴素的爬山法：随机交换两个学生，分数变高就接受。实现只要十几行，收敛飞快——但总停在「还行」的方案上。

模拟退火的洞察是：在高温阶段以概率接受更差的解，随温度下降，接受概率趋近于零。设新解与当前解的分数差为 $\Delta E$（越低越差），接受劣解的概率：

$$ P(\text{accept}) = \exp\left(-\frac{\Delta E}{T}\right) $$

温度按几何日程衰减：$T_{k+1} = \alpha T_k$，本项目取 $\alpha = 0.95$、初始 $T_0 = 100$。同样是 3 秒预算，爬山法平均分 82，模拟退火 91，且方差明显更小。

工程上的取舍

决策	选择	代价
运行位置	纯前端 WebWorker	首次加载多一个文件
数据存储	localStorage	换设备需导出导入
可视化	Canvas 逐帧重绘	代码量更多

上线一学期后，朋友的反馈是：「它给出的方案不总是我心里的最优，但从来不会离谱。」——对算法工程来说，这就是好评。

东京五日：一台相机和三卷胶片

Sat, 18 Jul 2026 00:00:00 GMT

出差顺带的五天假期，塞了一台老胶片机和三卷过期胶卷进包，在东京街头乱走。

没有行程表，也没有必须打卡的店。谷中根津一带的坡道、傍晚的昭和通、凌晨四点的筑地外围——快门按下去的时候大多没在想「这张能不能发」，更多是「这个瞬间好像值得留」。

三卷胶片冲出来一卷，另外两卷还在防潮箱里。等待的时间也是摄影的一部分。

一些没有用途的照片

胶片的好处是每按一次快门都有成本，于是你会开始认真看。这座城市值得认真看。

回头把剩下两卷冲出来，再补一篇。