feat(v1.2.5): 优化首页滚动顺滑性、恢复整屏吸附并提升 Halo 要求至 2.27

- 首页固定模糊半径只改 opacity；Hero 离屏停绘；Navbar 滚动状态去重
- 恢复首屏整屏吸附：仅接管 0 ↔ 内容区顶部边界，scrollend + 600ms 兜底解锁
- CSS scroll-snap proximity 实际不吸附（缺页面顶部吸附点），已移除避免与 scrollTo 冲突
- 版本 1.2.5，requires >=2.27.0；源码仓库与问题反馈改为 git.nxxy335.top
- 更新 README / FAQ / 开发指南 / 更新日志，补充性能与发版说明

docs/.vitepress/config.mts

@@ -80,7 +80,7 @@ export default defineConfig({
     ],
 
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/nxxy335top/halo-theme-WarmIsland' }
+      { icon: 'github', link: 'https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland', ariaLabel: '源码仓库' }
     ],
 
     search: {

docs/changelog.md

@@ -1,5 +1,30 @@
 # 更新日志
 
+## v1.2.5
+
+### 兼容性与元数据
+
+- ⬆️ Halo 版本要求提升至 **2.27.0+**（页面布局契约、微信读书页面依赖 2.27 的能力）
+- 🔗 源码仓库与问题反馈地址统一为 `https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland`
+- 📚 完善安装、开发、FAQ 文档，修正过时的技术栈与构建打包说明
+
+### 性能优化
+
+- 🚀 **首页滚动顺滑性**：移除逐帧改写全屏 `backdrop-filter` 模糊半径的逻辑。
+  旧实现让 Chromium 每个滚动帧都重做一次全屏背景采样 + 高斯模糊，是首页掉帧主因；
+  现改为固定模糊半径 + 只调整 `opacity`（合成层操作），并缓存进度值避免重复写 DOM
+- 🚀 **首屏离屏即停**：滚过首屏后 Hero 已被不透明内容区完全盖住，此时隐藏 Hero
+  并暂停光球动画，长页面后半段不再有额外绘制
+- 🚀 **首屏整屏吸附回归（顺滑版）**：v1.2.5 初版改用 CSS `scroll-snap: y proximity` 后吸附
+  实际失效——内容区顶部是唯一吸附点、页面顶部 `0` 没有吸附点，`proximity` 几乎不触发；
+  换成 `mandatory` 又会把长内容反复拉回内容区顶部。现改为**边界吸附**：只在
+  `0 ↔ 内容区顶部` 接管一次滚轮 / 触摸，进入内容区后完全交给原生滚动惯性；解锁用
+  `scrollend` + 600ms 兜底（原为固定 800ms 输入锁），已在目标位置时不再接管
+- 🚀 **导航栏滚动状态去重**：只在状态真正变化时写 class，不再每帧触发样式重算
+- ♿ 补充 `prefers-reduced-motion` 支持：减少动态效果时关闭平滑滚动与光球 / 指示箭头动画，
+  吸附改为即时定位（不再关闭吸附）
+- 🖼️ 首页文章列表继续使用 `content-visibility: auto` 跳过视口外渲染，图片保持懒加载
+
 ## v1.2.4
 
 ### 问题修复

docs/config/footer.md

@@ -80,7 +80,7 @@ ICP 备案号通常需要链接到工信部的备案查询页面。主题会自
 footer_socials:
   - platform: GitHub
     icon: fa-brands fa-github
-    url: https://github.com/your-username
+    url: https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland
   - platform: 微博
     icon: fa-brands fa-weibo
     url: https://weibo.com/your-username

docs/customize/development.md

@@ -27,8 +27,8 @@ git --version  # git version 2.x.x
 ## 克隆与安装
 
 ```bash
-git clone https://github.com/your-username/WarmIsland.git
-cd WarmIsland
+git clone https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland.git
+cd halo-theme-WarmIsland
 pnpm install
 ```
 
@@ -66,6 +66,36 @@ ZIP 根目录直接放 `theme.yaml` / `settings.yaml` / `templates/`，不要额
 > `Template index was not found.` 并让首页 404。现在打包脚本会先校验
 > `index.html` 等模板、资源目录与版本号，不满足即报错退出。
 
+## 性能与滚动顺滑
+
+首页滚动曾经卡顿，根因不是 DOM 数量，而是「每帧高成本绘制 + 劫持滚动输入」：
+
+| 问题 | 原因 | 现在的做法 |
+|------|------|------------|
+| 全屏模糊逐帧重算 | 滚动回调每帧改写 `backdrop-filter: blur(Npx)`，Chromium 每帧重做一次全屏背景采样 + 高斯模糊 | 模糊半径固定，滚动只改整层 `opacity`（合成层操作） |
+| 吸附吞掉滚动惯性 | 旧实现在 `wheel` / `touchend` 上 `preventDefault()` 并固定锁 800ms | 保留整屏吸附，但只在 `0 ↔ 内容区顶部` 边界接管一次；进入内容区后完全交给原生滚动。解锁用 `scrollend` + 600ms 兜底，已在目标位置时不再接管 |
+| Hero 一直绘制 | 固定全屏 Hero 的光球动画与模糊层在滚过首屏后仍在跑 | 内容区盖满视口后加 `wi-hero--offscreen` 隐藏并暂停动画 |
+| 状态反复写入 | 导航栏每个滚动帧都 `classList.add/remove` | 缓存状态，只在变化时写 |
+
+**为什么吸附不用 CSS `scroll-snap`**：v1.2.5 初版试过 `html { scroll-snap-type: y proximity }`
+加内容区 `scroll-snap-align: start`，实际几乎不吸附——只有内容区顶部一个吸附点，页面顶部
+`0` 没有吸附点，`proximity` 只在滚动结束位置接近吸附点时才生效；换成 `mandatory` 则会在
+长内容的每次滚动后把页面拉回内容区顶部，正文无法阅读。`prefers-reduced-motion` 下 CSS 方案
+还会直接关闭吸附。因此改为脚本的边界吸附，CSS 侧不再设置 `scroll-snap`，避免与 `scrollTo`
+平滑动画抢夺滚动位置。
+
+涉及文件：`src/pages/index.astro`（滚动渐隐 + 边界吸附脚本）、`src/components/HeroSection.astro`（模糊层与离屏规则）、
+`src/components/Navbar.astro`（状态去重）、`src/styles/main.scss`（平滑滚动与 reduced-motion）。
+
+**可调项**：后台「总体样式 → 启用动效」可一键关闭滚动渐入，「Hero 首屏」可关闭整个 Hero；
+系统开启「减少动态效果」（`prefers-reduced-motion: reduce`）时，平滑滚动与光球 / 箭头动画停用，
+吸附改为即时定位（仍然可用）。长列表使用 `content-visibility: auto` 跳过视口外渲染，
+图片统一 `loading="lazy" decoding="async"`。
+
+> 改动滚动逻辑后建议用浏览器 Performance 面板录制一次首页滚动：滚动帧里不应出现大面积
+> `Paint` / `Update Layer Tree`；也不要在 `scroll` 回调里读取 `getBoundingClientRect()` 之类
+> 会强制同步布局的属性（当前实现只在初始化 / resize 时测量内容区位置）。
+
 ## 项目结构
 
 ```
@@ -130,26 +160,26 @@ WarmIsland/
 
 | 技术 | 版本 | 用途 |
 |------|------|------|
-| [Astro](https://astro.build) | 5.x | 静态站点生成，组件开发 |
-| [vite-plugin-halo-theme](https://github.com/halo-sigs/vite-plugin-halo-theme) | - | Halo 主题开发集成 |
-| [Thymeleaf](https://www.thymeleaf.org/) | - | Halo 服务端模板引擎 |
+| [Halo](https://www.halo.run/) | 2.27+ | 博客运行时，提供 Finder API 与主题渲染 |
+| [Astro](https://astro.build) | 6.x | 组件开发，构建输出静态 `.html` 模板 |
+| [Thymeleaf](https://www.thymeleaf.org/) | - | Halo 服务端模板引擎（源码里直接写 `th:*`） |
 
 ### 前端技术
 
 | 技术 | 用途 |
 |------|------|
-| [Vue 3](https://vuejs.org/) | 交互组件（目录、点赞、无限滚动等） |
-| [SCSS](https://sass-lang.com/) | 样式预处理 |
-| [Prism.js](https://prismjs.com/) | 代码高亮 |
-| [LightGallery](https://www.lightgalleryjs.com/) | 图片灯箱 |
+| [SCSS](https://sass-lang.com/) | 样式预处理，CSS 变量驱动的配色系统 |
+| 原生 JavaScript | 滚动、菜单、主题切换、无限滚动等交互，无前端框架运行时 |
+| [LightGallery](https://www.lightgalleryjs.com/) | 图片灯箱（可选） |
+| Halo 插件生态 | 评论、代码高亮、服务端字数统计等由 Halo 与可选插件提供 |
 
 ### 构建工具
 
 | 技术 | 用途 |
 |------|------|
-| [Vite](https://vitejs.dev/) | 构建打包 |
+| [Vite](https://vitejs.dev/)（Astro 内置） | 资源打包与内容哈希 |
 | [pnpm](https://pnpm.io/) | 包管理 |
-| [TypeScript](https://www.typescriptlang.org/) | 类型安全 |
+| [TypeScript](https://www.typescriptlang.org/) | 类型定义（`env.d.ts` / `pages.ts`） |
 
 ## 模板语法
 

docs/faq.md

@@ -24,7 +24,7 @@ ZIP 里缺少 `templates/index.html` 时，渲染首页找不到 `index` 模板
 
 检查以下几点：
 
-1. 确认 Halo 版本 >= 2.26.0
+1. 确认 Halo 版本 >= 2.27.0
 2. 确认主题已启用
 3. 清除浏览器缓存后重试（Ctrl+Shift+R 强制刷新）
 4. 检查 Halo 后台日志是否有报错
@@ -170,7 +170,7 @@ v1.2.1 起安装包会保留各版本的哈希资源（v1.1.7 之后全部覆盖
 
 ### 如何报告 Bug？
 
-请在 [GitHub Issues](https://github.com/sunny-335/halo-theme-WarmIsland/issues) 中提交，包含以下信息：
+请在 [源码仓库 Issues](https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland/issues) 中提交，包含以下信息：
 
 - Halo 版本
 - 主题版本

docs/guide/getting-started.md

@@ -27,7 +27,7 @@ WarmIsland（暖屿）是一款为 [Halo](https://halo.run) 打造的博客主
 
 ### 方式二：本地上传安装
 
-1. 从 [GitHub Releases](https://github.com/nxxy335top/halo-theme-WarmIsland/releases) 下载最新版本的 `.zip` 安装包
+1. 从 [源码仓库](https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland) 的 Releases / 发行版页面下载最新版本的 `.zip` 安装包
 2. 登录 Halo 后台管理控制台
 3. 进入 **主题** → **安装** → 选择 **本地上传**
 4. 上传下载的 `.zip` 文件

docs/index.md

@@ -13,8 +13,8 @@ hero:
       text: 配置项
       link: /config/basic
     - theme: alt
-      text: GitHub
-      link: https://github.com/nxxy335top/halo-theme-WarmIsland
+      text: 源码仓库
+      link: https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland
 
 features:
   - title: 🎨 精致视觉