AI 摘要
这个博客基于 Fuwari 主题，并进行了彻底的工程化重构。为了追求极致的加载速度和“十年之约”所要求的离线生存能力，我重写了大部分底层逻辑。
本指南仅包含核心原理和涉及的文件。如果你对具体的实现细节感兴趣，请查阅本站的 Git 仓库。
1. 文章置顶与排序
原理：在 frontmatter 中引入 order 字段。在 src/utils/content-utils.ts 中，排序逻辑被修改为优先判断 order 值（1 为置顶，-1 为置底），随后才按发布日期倒序排列。
2. 自动化系列文章
原理：通过 series 字段自动关联文章。不仅有专门的汇总页，还在文章页侧边栏添加了 Series.astro 挂件，利用 Astro 的静态集合 API 在构建时自动提取同一系列的其他篇目。
3. 自定义 MusicPlayer (弃用 APlayer)
原理：为了减少外部依赖并获得更好的性能，我移除了 APlayer，转而使用原生 JavaScript 类继承 HTMLElement 编写了一个 Web Component。它能完美配合 Swup 进行无刷新跳转，且只加载本地音频资源。
- 组件:
src/components/widget/MusicPlayer.astro - 配置:
src/configs/music.ts
4. 全局生命周期管理 (适配 Swup)
原理：这是最核心的重构。为了解决异步加载导致的脚本重复绑定或失效问题，我开发了 src/utils/lifecycle.ts。通过 setupComponent 函数，为每个 .astro 组件提供标准化的 init 和 cleanup 钩子。
5. “十年之约”离线生存流
原理：为了确保即使 GitHub、Unsplash 或第三方 CDN 挂掉，博客依然完整：
- 图片本地化:
localize-external-images.ts在构建时扫描 Markdown，自动下载外链图并改写源码路径。 - GitHub 静态化:
staticize-github-cards.ts抓取仓库数据（Star/Fork/头像）并直接持久化到 Markdown 指令中。 - 零外链图标: 移除了
astro-icon依赖，所有图标通过src/constants/icons.ts以 SVG 字符串形式在构建时内联。
6. 自适应主题色
原理：利用 Sharp 在构建时提取文章封面图的平均色，计算出 HSL 中的 Hue 值，并通过 data-hue 属性注入 DOM。配合全局 CSS 变量 --hue，实现每篇文章都有独特的视觉风格。
7. 毛玻璃 (Glass Mode)
原理：不再使用 Svelte，全量迁移到 Astro + Tailwind。通过在 <html> 标签上切换 .glass-mode 类，并利用 CSS backdrop-filter 和透明度变量（定义在 src/styles/variables.css 中）实现细腻的半透明效果。
技术提醒： 改动如此之大的代价是维护成本。强烈建议在每次修改后运行：
pnpm check # 检查 Astro 组件pnpm lint # 运行 Biome 代码校验pnpm build # 验证全自动化流水线如果构建产物中出现了死链或损坏的资源，check-integrity.ts 会直接中断构建并报错。
部分内容可能已过时
0 条评论