From 6ab408ca4f0c0d2fc943a477b8f1e4c491b2f0f6 Mon Sep 17 00:00:00 2001 From: nxxy335 Date: Wed, 11 Nov 2026 22:47:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(v1.2.7):=20=E7=B2=BE=E7=AE=80=20README=20?= =?UTF-8?q?=E8=87=AA=E8=AF=81=E5=BC=8F=E5=86=85=E5=AE=B9=E5=B9=B6=E9=87=8D?= =?UTF-8?q?=E6=8E=92=E7=AB=A0=E8=8A=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 移除开发者自证、回归检查清单与重复的「不加载远程脚本」类宣言；按安装 → 功能 → 插件 → 隐私 → 开发 → 声明重排章节（331 → 237 行）。5.1 逐项披露、许可表与原创声明完整保留；changelog 同步记录。 --- README.md | 345 +++++++++++++++++----------------------------- docs/changelog.md | 3 + 2 files changed, 129 insertions(+), 219 deletions(-) diff --git a/README.md b/README.md index e53fe5f..2647f9c 100644 --- a/README.md +++ b/README.md @@ -2,36 +2,115 @@ 暖如灯火，静如留白。暖屿以柔和的色调和舒缓的节奏回归内容本身，为记录与阅读留出一方安静从容的角落。 -> 本项目使用 AI 辅助开发。开发者已按 Halo 主题规范完成代码审查、构建产物核验、外部资源审计与主要模板的回归检查清单（见[验证与回归测试](#验证与回归测试)）；主题不加载远程脚本、不动态下载代码、不进行未披露的数据收集。 +![WarmIsland Preview](https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland/raw/branch/main/WarmIsland%20Preview.webp) + +> 预览图随安装包分发（包根目录 `WarmIsland Preview.webp`）。 ## 环境要求 -- Halo **2.27.0 及以上**（页面布局契约、微信读书页面均依赖 2.27 的新能力） -- v1.2.0 起内置主题配色系统（纯 CSS 变量实现）；更低版本的 Halo 请使用主题 v1.1.x +- Halo **2.27.0 及以上**（页面布局契约与微信读书页面依赖 2.27 的新能力） +- 更低版本的 Halo 请使用主题 v1.1.x；v1.2.0 起内置纯 CSS 变量实现的主题配色系统 + +## 安装 + +1. 下载最新 Release 的 ZIP 安装包 +2. Halo 后台 → 主题管理 → 安装主题 → 上传 ZIP +3. 点击「启用」 + +从源码构建： + +```bash +git clone https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland.git +cd halo-theme-WarmIsland +pnpm install +pnpm release # build → snapshot → package +``` + +`pnpm build` 只生成 `templates/`，ZIP 由 `pnpm package` 输出到 `dist/warm-island-.zip`；安装包同时含 `docs/*.md` 与预览图，便于离线查阅。 + +> **升级后首页 404「Template index was not found」**：ZIP 中缺少 `templates/`（源码打包时漏了构建步骤），请换用完整安装包重新上传，详见 [FAQ 安装相关](https://nxxy335.top/WarmIsland/faq.html)。 +> +> **升级后整站没了样式**：Halo 页面缓存或反向代理仍留着上一版 HTML，其引用的哈希 CSS 已被删除。在后台执行一次「清理缓存」并刷新 CDN / Nginx 缓存即可；主题自 v1.2.1 起会把历史哈希资源一并打进安装包。 +> +> **改了主题或配色后部分页面不生效**：若安装了「页面静态缓存」插件，需手动点一次「刷新页面缓存」，详见 [FAQ](https://nxxy335.top/WarmIsland/faq.html)。 ## 特点 -1. **响应式设计** — 适配桌面端与移动端，支持暗色模式，移动端使用动态视口单位适配地址栏 -2. **插件兼容性** — 适配 10 款常用 Halo 插件，安装即用；提供页面布局契约，插件前台页面自动复用主题外观 -3. **内置灯箱** — 主题内置 LightGallery 灯箱（GPLv3，随主题自托管打包），支持 EXIF 信息展示；安装 lightgallery.js 插件后自动禁用 +1. **响应式设计** — 桌面 / 移动端适配、暗色模式，移动端用动态视口单位适配地址栏 +2. **插件兼容** — 适配 10 款常用 Halo 插件，提供页面布局契约，插件前台页面自动复用主题外观 +3. **内置灯箱** — 随包自托管的 LightGallery（GPLv3），支持 EXIF 展示；安装 lightgallery.js 插件后自动让位 4. **可配置性** — 17 个设置分组、126 个配置项，几乎所有模块可独立开关 -5. **性能优化** — 服务端字数统计（API 扩展包）、图片懒加载与响应式缩略图、首屏整屏吸附（仅首屏边界接管，内容区保留原生滚动）、Hero 离屏停绘、CSS/HTML 压缩；详见[开发指南 - 性能与滚动顺滑](https://nxxy335.top/WarmIsland/customize/development.html) -6. **零默认外部请求** — 所有脚本、样式、字体、图标、句子库、主题图标均随主题自托管，默认不向任何第三方发起自动请求；详见[外部资源与隐私](#外部资源与隐私) -7. **页面布局契约** — 提供 `templates/layout.html`，插件页面不再回退到 Halo 内置布局 +5. **性能优化** — 服务端字数统计（API 扩展包）、图片懒加载与响应式缩略图、首屏整屏吸附（仅边界接管，内容区保留原生滚动）、Hero 离屏停绘、CSS/HTML 压缩；详见[开发指南 - 性能与滚动顺滑](https://nxxy335.top/WarmIsland/customize/development.html) +6. **页面布局契约** — 提供 `templates/layout.html`，插件页面不再回退到 Halo 内置布局 -## 预览 +## 主要功能 -![WarmIsland Preview](https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland/raw/branch/main/WarmIsland%20Preview.webp) +### 首页 -> 预览图同时随安装包分发（包根目录 `WarmIsland Preview.webp`），离线查看制品时也可打开。 +- Hero 首屏：明暗双背景图、大标题 / 副标题独立配色、描述文案（默认「无」；API 字段默认预填 `https://v1.hitokoto.cn/`，仅「一言」模式生效，清空则使用内置本地句子库；可选自定义文案与自动刷新）、下滑箭头平滑滚动 +- 欢迎弹窗：默认显示纯本地静态欢迎语，支持 5 种位置、会话去重开关；仅在显式配置自定义 IP 定位 API 时才显示访客所在地（见[外部资源与隐私](#外部资源与隐私)） +- 滚动吸附：首屏与内容区之间滚轮 / 触摸自动吸附，进入内容区后恢复原生自由滚动 +- 文章卡片：可配置显示字数（依赖 API 扩展包）、阅读量、分类、标签、摘要行数 + +### 文章 + +- 目录（TOC）：桌面端侧栏 + 移动端抽屉，滚动高亮、展开模式可选 +- 代码高亮：由代码高亮插件 / API 扩展包输出，主题提供 Warm / Cold 两套本地配色 +- 上下篇导航、相关推荐、分享按钮、赞赏、版权声明可独立开关；微信分享改为复制文章链接 +- 字数与阅读时间：优先使用 API 扩展包的服务端统计，未安装时前端计算兜底 + +### 全局 + +- 点击特效：核心价值观 / 爱心 / 烟花 / 粒子等 8 种效果可选，也可关闭 +- 页脚全站统计：文章、分类、评论、访问、点赞、总字数，支持开关与统计项选择（默认开启） +- 动效：呼吸动画、滚动渐入，可独立关闭 +- 备案信息：ICP 与公网安备号，公网安备自动带徽标 + +## 已适配插件 + +| 插件名称 | 插件标识 | 适配页面路由 | 说明 | +|----------|---------|-------------|------| +| [瞬间](https://halo.run/store/apps/app-SnwWD) | `PluginMoments` | `/moments` | 瞬间动态页面，支持点赞、评论、标签筛选、顶部封面 | +| [图库](https://halo.run/store/apps/app-BmQJW) | `PluginPhotos` | `/photos` | 图片展示页面，支持分组、灯箱预览 | +| [友情链接（链接管理）](https://halo.run/store/apps/app-hfbQg) | `PluginLinks` | `/links` | 友链展示页面，支持随机排列、随机传送门、评论区开关；同一插件的 RSS 订阅驱动「订阅」页面 | +| [装备管理](https://github.com/chengzhongxue/plugin-equipment) | `equipment` | `/equipments` | 装备展示页面，按分组展示，支持封面图 | +| [豆瓣](https://github.com/chengzhongxue/plugin-douban) | `plugin-douban` | `/douban` | 豆瓣记录页面，支持类型 / 状态 / 标签筛选，默认音乐；需插件 **v1.2.6+**（SQLite 数据结构） | +| [Steam 信息展示](https://github.com/Tim0x0/halo-plugin-steam) | `PluginSteam` | `/steam` | Steam 游戏库页面，含用户资料、统计数据、最近游玩、游戏库分页 | +| [微信读书](https://github.com/yeora26/halo-weread-plugin) | `halo-weread-plugin` | 自定义页面 | 书架展示页面，见下方「自定义页面模板」 | +| [记得](https://github.com/yyliucha/plugin-important-dates) | `plugin-important-dates` | `/important-dates` | 重要日期 / 牵挂的人 / 爱车双视图页面，见下方「扩展页面」 | +| [文章组件](https://github.com/acanyo/plugin-content-widgets) | `plugin-content-widgets` | 文章内 | 提示框、标签页、时间线等内容组件，主题已映射 `--xhhao-com-*` 变量，自动跟随明暗模式 | +| [API 扩展包](https://github.com/HowieHz/halo-plugin-extra-api) | `extra-api` | 全站 | 服务端字数统计、中英文混排排版、可选服务端代码高亮 | + +> 插件需单独安装；未安装时对应页面或功能自动隐藏 / 降级，不会报错。 +> +> **「朋友圈」（`plugin-friends`）插件已不再提供**：原先的 feed / RSS 聚合能力由官方「链接管理」（PluginLinks）插件的订阅取代，对应下方的「订阅」自定义页面模板。主题保留 `friends.html` 与「朋友圈」设置分组仅用于兼容旧站点，新站点请勿再依赖；插件不可用时会显示空状态。 + +## 自定义页面模板 + +在 Halo 后台「页面 → 新建 → 自定义模板」中选择使用（页面地址由 slug 决定，无固定路由）： + +| 模板名 | 模板文件 | 说明 | +|--------|---------|------| +| 留言板 | `page_messageboard.html` | 留言墙页面，标题与副标题可配置 | +| 订阅 | `page_subscriptions.html` | 博友文章订阅动态，由官方链接管理插件的 RSS 订阅提供，支持分页 / 下滑加载与列表 / 网格布局 | +| 微信读书 | `weread.html` | 微信读书书架展示，依赖微信读书插件，访客免登录查看 | + +## 灯箱集成 + +主题内置 LightGallery 2.9.0（GPLv3，与主题的 GPL-3.0 一致），为图片提供放大预览与 EXIF 展示。如安装 [lightgallery.js](https://www.lightgalleryjs.com/) 灯箱插件，内置灯箱自动禁用，改由插件接管。其路径匹配规则与 DOM 节点选择器： + +| 页面 | 路径匹配规则 | 匹配区域 DOM 节点 | +|------|-------------|-------------------| +| 文章详情页 | `/archives/*` | `.wi-post__body` | +| 瞬间页 | `/moments` | `.wi-moments-page__content` | +| 图库页 | `/photos` | `.wi-photos-page__grid` | +| 自定义页面 | 用户自定义 | `.wi-page__body` | + +> 自定义页面的路径匹配由用户自行设定，此处仅提供 DOM 节点选择器 `.wi-page__body`。 ## 外部资源与隐私 -本章节对应 [Halo 应用市场审核指南](https://docs.halo.run/developer-guide/app-store/app-review-guidelines) 1.4 / 4.4.4 / 5.1，逐项说明服务名称、用途、数据类型、默认状态与关闭方法。 - -### 默认行为 - -**默认配置下，主题不会自动向任何第三方服务发起请求。** 页面加载的 CSS、JS、字体（LXGW WenKai 本地分片）、图标、主题 Logo、一言句子库全部来自站点自身的 `/themes/warm-island/assets/`，不经过 CDN，也不使用 `preconnect` / `dns-prefetch`。已移除的远程依赖见下方[自托管与许可](#自托管与许可)。 +默认配置下，主题不会自动向任何第三方服务发起请求：CSS、JS、字体（LXGW WenKai 本地分片）、图标、Logo 与一言句子库均来自站点自身的 `/themes/warm-island/assets/`，不经过 CDN，也不使用 `preconnect` / `dns-prefetch`。 ### 逐项说明 @@ -54,20 +133,11 @@ | IP 定位主接口 | `welcome_popup_api` | `https://myip.ipip.net/json` 或 `https://r.inews.qq.com/api/ip2city?otype=json` | | IP 定位备选接口 | `welcome_popup_fallback_api` | 同上两个地址任选其一，主接口失败时兜底 | -**描述文案来源默认为「无」**，可选「一言」「自定义」，此时不渲染一言元素、不发起任何请求。API 字段默认预填 -`https://v1.hitokoto.cn/`（仅「一言」模式生效）；选择「一言」或「自定义」后若把 API 留空，则使用主题内置的本地句子库（零外部请求）。 -**只有填写后才会向该地址发起请求**，需自行在站点隐私说明中披露，详见本章节「逐项说明」与下方「隐私说明（5.1）」。 +**描述文案来源默认为「无」**，此时不渲染一言元素、不发起任何请求。API 字段默认预填 `https://v1.hitokoto.cn/`（仅「一言」模式生效）；选择「一言」或「自定义」后若留空，则回退到主题内置的本地句子库（零外部请求）。只有填写后才会向该地址发起请求，第三方可见访客 IP / User-Agent，需自行在站点隐私说明中披露。 -IP 定位接口同样默认留空；**填写后会把访客 IP 发送给该第三方服务换取地理位置**， -需自行在站点隐私说明中披露，详见本章节「逐项说明」与下方「隐私说明（5.1）」。主题不会代替站点做这项声明。 +两个 IP 定位接口同样默认留空；填写后会把**访客 IP**发送给该第三方服务换取粗略地理位置，需自行在站点隐私说明中披露。 -> 三个可选 API 配置项的 `help` 只保留功能说明（候选地址、留空回退规则）；完整的第三方数据流向与 -> 隐私披露统一在 README「外部资源与隐私」章节和配置文档中说明，主题设置界面不重复展示冗长文案。 -> 字段是否显示由对应功能开关决定，且字段可见不等于发起请求：默认值与模板的条件渲染共同保证默认零外部请求。 - -> 自定义 API 属于**站点管理员主动配置**的可选能力：一旦填写，浏览器会按设置向该第三方发起请求。请自行评估服务商的隐私政策，并在站点隐私说明中补充披露；主题不会代替站点做这项声明。 - -### 隐私说明（5.1） +### 隐私说明 | 项目 | 说明 | | --- | --- | @@ -80,163 +150,24 @@ IP 定位接口同样默认留空；**填写后会把访客 IP 发送给该第 ### 自托管与许可 -- **已移除的远程依赖**：`cdn.jsdelivr.net` 预连接与预解析（原出现在全部模板）、PrismJS 1.29.0 核心与 `autoloader`（会按代码语言从 CDN 动态拉取并执行组件）、`qrcode-generator`、默认的一言与 IP 定位接口。 -- **代码高亮**：主题不再自带 Prism.js 运行时。语法高亮请安装 Halo 应用市场的代码高亮插件，或启用「API 扩展包」的服务端代码高亮；主题只提供两套自托管的 `.token` 配色（`assets/vendor/prism-warm.css` / `prism-cold.css`），由「文章 → 代码高亮主题」切换。 -- **字体**：[霞鹜文楷 LXGW WenKai](https://github.com/lxgw/LxgwWenKai) 以 [SIL OFL 1.1](https://openfontlicense.org/) 发布，由 `cn-font-split` 切分为本地 woff2 分片随主题分发；字体来源与版权声明保留在 `public/assets/fonts/LXGWWenKai/result.css`，上游完整的版权声明、保留字体名条款与 **OFL 1.1 许可证全文**随包存放于 `public/assets/fonts/LXGWWenKai/OFL.txt`（构建后为 `templates/assets/fonts/LXGWWenKai/OFL.txt`）。上游的附加许可明确允许把字体切分 / 转换为 WOFF2 仅用于网页字体交付，本主题的使用方式与之相符；无远程字体请求。 -- **灯箱**：LightGallery 2.9.0 以 GPLv3 发布，本主题同样采用 GPL-3.0，按开源许可条款使用（非商业授权）；已去除占位 `licenseKey`，控制台不再出现 `license key is not valid for production use`。 +- **代码高亮**：主题不自带 Prism.js 运行时。语法高亮请安装 Halo 应用市场的代码高亮插件，或启用「API 扩展包」的服务端代码高亮；主题只提供两套自托管的 `.token` 配色（`assets/vendor/prism-warm.css` / `prism-cold.css`），由「文章 → 代码高亮主题」切换。 +- **字体**：[霞鹜文楷 LXGW WenKai](https://github.com/lxgw/LxgwWenKai) 以 [SIL OFL 1.1](https://openfontlicense.org/) 发布，由 `cn-font-split` 切分为本地 woff2 分片随主题分发；字体来源与版权声明保留在 `public/assets/fonts/LXGWWenKai/result.css`，上游完整的版权声明、保留字体名条款与 **OFL 1.1 许可证全文**随包存放于 `public/assets/fonts/LXGWWenKai/OFL.txt`（构建后为 `templates/assets/fonts/LXGWWenKai/OFL.txt`）。上游附加许可允许把字体切分 / 转换为 WOFF2 用于网页字体交付。 +- **灯箱**：LightGallery 2.9.0 以 GPLv3 发布，本主题同样采用 GPL-3.0，按开源许可条款使用（非商业授权）。 - **图标**：来源与协议见[图标与字体来源](#图标与字体来源)。 -## 内容渲染安全（4.4.2） - -主题对「站点内容 / 用户生成内容」与「管理员显式配置」采取不同的渲染策略，避免把不可信字符串直接拼进可执行上下文： - -| 场景 | 处理方式 | -| --- | --- | -| 文章标题、摘要、作者、封面（结构化数据） | 不再用 `th:utext` 把变量拼进 `application/ld+json` 脚本文本。字段先经 Thymeleaf 转义写入 ``，前端读取后用 `JSON.stringify` + `textContent` 生成 JSON-LD，内容里的尖括号不会被解析为标签 | -| 瞬间正文 | 插件已渲染的 `content.html` 用 `th:utext` 原样呈现；`html` 缺失时的 `content.raw` 兜底改用 `th:text` 转义输出，不再当作 HTML 执行 | -| 文章正文、单页正文、评论 | 使用 Halo 核心 / 评论插件输出的已处理 HTML，主题不二次拼接脚本 | -| 常规模板变量 | 统一用 `th:text` / `th:attr`（转义输出）；`th:utext` 仅用于上述受控 HTML 与管理员自定义内容 | -| 链接与图片 | `target="_blank"` 一律带 `rel="noopener noreferrer"`；所有 `` 提供 `alt` / `th:alt` | - -以下三类内容由**管理员在后台显式填写**，属于主题的设计能力，写入权限由 Halo 后台角色控制，不属于访客输入： - -- `style.accent_color` 与 6 个 Hero 配色项：`settings.yaml` 中声明为 `$formkit: color`，由颜色选择器约束为 `#RRGGBB`，仅用于生成内联 CSS 变量； -- `style.custom_css`（自定义 CSS）、`footer.footer_custom_html`（页脚自定义 HTML，如统计代码）：按设计意图原样输出，用途已在设置项说明中标注。若站点允许多名作者或开放后台编辑权限，请自行评估这些字段的信任边界。 - -字符串截取前先判空（`#strings.substring('', 0, 1)` 会抛越界异常）已在全部 12 处友链 / 留言 / 订阅 / 插件页面兜底，避免空值导致页面 500；控制台无报错与键盘可达性、深浅色对比度一起列入下方人工回归清单。 - -## 已适配插件 - -| 插件名称 | 插件标识 | 适配页面路由 | 说明 | -|----------|---------|-------------|------| -| [瞬间](https://halo.run/store/apps/app-SnwWD) | `PluginMoments` | `/moments` | 瞬间动态页面，支持点赞、评论、标签筛选、顶部封面 | -| [图库](https://halo.run/store/apps/app-BmQJW) | `PluginPhotos` | `/photos` | 图片展示页面，支持分组、灯箱预览 | -| [友情链接（链接管理）](https://halo.run/store/apps/app-hfbQg) | `PluginLinks` | `/links` | 友链展示页面，支持随机排列、随机传送门、评论区开关；同一插件的 RSS 订阅驱动「订阅」页面 | -| [装备管理](https://github.com/chengzhongxue/plugin-equipment) | `equipment` | `/equipments` | 装备展示页面，按分组展示，支持封面图 | -| [豆瓣](https://github.com/chengzhongxue/plugin-douban) | `plugin-douban` | `/douban` | 豆瓣记录页面，支持类型/状态/标签筛选，默认音乐；需插件 **v1.2.6+**（SQLite 数据结构） | -| [Steam 信息展示](https://github.com/Tim0x0/halo-plugin-steam) | `PluginSteam` | `/steam` | Steam 游戏库页面，含用户资料、统计数据、最近游玩、游戏库分页 | -| [微信读书](https://github.com/yeora26/halo-weread-plugin) | `halo-weread-plugin` | 自定义页面 | 书架展示页面，见下方「自定义页面模板」 | -| [记得](https://github.com/yyliucha/plugin-important-dates) | `plugin-important-dates` | `/important-dates` | 重要日期 / 牵挂的人 / 爱车双视图页面，见下方「扩展页面」 | -| [文章组件](https://github.com/acanyo/plugin-content-widgets) | `plugin-content-widgets` | 文章内 | 提示框、标签页、时间线等内容组件，主题已映射 `--xhhao-com-*` 变量，自动跟随明暗模式 | -| [API 扩展包](https://github.com/HowieHz/halo-plugin-extra-api) | `extra-api` | 全站 | 服务端字数统计、中英文混排排版、可选服务端代码高亮 | - -> **注意**：插件需要单独安装，安装后主题会自动适配对应页面。若未安装某插件，对应页面或功能自动隐藏/降级，不会报错。 -> -> **「朋友圈」（`plugin-friends`）插件已不再提供**：原先的 feed / RSS 聚合能力由官方 -> **「链接管理」（PluginLinks）插件的订阅**取代，对应下方的「订阅」自定义页面模板。 -> 主题保留 `friends.html` 与「朋友圈」设置分组仅用于兼容旧站点，新站点请勿再依赖； -> 插件不可用时会显示空状态，不会报错。 - -## 自定义页面模板 - -在 Halo 后台「页面 → 新建 → 自定义模板」中选择使用（页面地址由 slug 决定，无固定路由）： - -| 模板名 | 模板文件 | 说明 | -|--------|---------|------| -| 留言板 | `page_messageboard.html` | 留言墙页面，标题与副标题可配置 | -| 订阅 | `page_subscriptions.html` | 博友文章订阅动态，由官方链接管理插件的 RSS 订阅提供，支持分页 / 下滑加载与列表 / 网格布局 | -| 微信读书 | `weread.html` | 微信读书书架展示，依赖微信读书插件，访客免登录查看 | - -## 主要功能 - -### 首页 - -- Hero 首屏：明暗双背景图、大标题/副标题独立配色、描述文案（默认「无」；API 字段默认预填 `https://v1.hitokoto.cn/`，仅「一言」模式生效，清空则使用内置本地句子库；可选自定义文案与自动刷新）、下滑箭头平滑滚动 -- 欢迎弹窗：默认显示纯本地静态欢迎语，支持 5 种位置、会话去重开关；仅在显式配置自定义 IP 定位 API 时才显示访客所在地（见[外部资源与隐私](#外部资源与隐私)） -- 滚动吸附：首屏与内容区之间滚轮/触摸自动吸附，进入内容区后恢复原生自由滚动 -- 文章卡片：可配置显示字数（依赖 API 扩展包）、阅读量、分类、标签、摘要行数 - -### 文章 - -- 目录（TOC）：桌面端侧栏 + 移动端抽屉，滚动高亮、展开模式可选 -- 代码高亮：由代码高亮插件 / API 扩展包输出，主题提供 Warm / Cold 两套本地配色；主题不加载任何远程高亮脚本 -- 上下篇导航、相关推荐、分享按钮、赞赏、版权声明可独立开关；微信分享改为复制文章链接，无需二维码库 -- 字数与阅读时间：优先使用 API 扩展包的服务端统计，未安装时前端计算兜底 - -### 全局 - -- 点击特效：核心价值观 / 爱心 / 烟花 / 粒子等 8 种效果可选，也可关闭 -- 页脚全站统计：文章、分类、评论、访问、点赞、总字数，支持开关与统计项选择（默认开启） -- 动效：呼吸动画、滚动渐入，可独立关闭 -- 备案信息：ICP 与公网安备号，公网安备自动带徽标 -- 鼠标光感跟随已移除（性能考量） - -## 灯箱集成 - -主题内置 LightGallery 灯箱，为图片提供放大预览功能，并支持 EXIF 信息展示。该库以 GPLv3 发布，本主题以 GPL-3.0 开源，按开源许可条款自托管使用；控制台不会出现商业授权提示。 - -### lightgallery.js 插件兼容 - -如安装 [lightgallery.js](https://www.lightgalleryjs.com/) 灯箱插件，主题内置灯箱将自动禁用，改由插件接管灯箱功能。以下为 lightgallery.js 插件的路径匹配规则和 DOM 节点选择器： - -| 页面 | 路径匹配规则 | 匹配区域 DOM 节点 | -|------|-------------|-------------------| -| 文章详情页 | `/archives/*` | `.wi-post__body` | -| 瞬间页 | `/moments` | `.wi-moments-page__content` | -| 图库页 | `/photos` | `.wi-photos-page__grid` | -| 自定义页面 | 用户自定义 | `.wi-page__body` | - -> **注意**：自定义页面的路径匹配由用户自行设定，此处仅提供 DOM 节点选择器 `.wi-page__body`。 - -## 安装 - -1. 下载主题最新 Release 的 ZIP 包 -2. 进入 Halo 后台 → 主题管理 → 安装主题 → 上传 ZIP 包 -3. 安装完成后点击「启用」 - -> **升级后首页 404「资源不存在 / Template index was not found」**：说明上传的 ZIP 里没有 `templates/` -> 模板文件（从源码仓库打包时漏了构建步骤）。请换用完整安装包重新上传，详见 [FAQ 安装相关](https://nxxy335.top/WarmIsland/faq.html)。 -> -> **升级后如果整站没了样式**：Halo 页面缓存或前置反向代理里可能还留着上一版本的 HTML， -> 它引用的 CSS 文件名带内容哈希，升级后已被删除，请求会直接 500。 -> 先在 Halo 后台执行一次「清理缓存」（并刷新 CDN / Nginx 缓存）即可。 -> 主题从 v1.2.1 起会把历史版本的哈希资源一并发进安装包，旧 HTML 也不会请求失败。 -> -> **升级主题或修改配色后，部分页面不生效**：如果安装了「页面静态缓存」插件， -> 它只随文章变更自动刷新，主题层的变更需要手动点一次「刷新页面缓存」， -> 详见 [FAQ：升级主题或修改配色后部分页面不生效](https://nxxy335.top/WarmIsland/faq.html)。 - -或从源码构建： - -```bash -git clone https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland.git -cd halo-theme-WarmIsland -pnpm install -pnpm release # build → snapshot → package（含外部资源审计） -``` - -`pnpm build` 只生成 `templates/`（模板 + 静态资源），不会产出 ZIP； -安装包由 `pnpm package` 生成到 `dist/warm-island-.zip`。安装包同时包含 `docs/*.md` 与预览图，便于离线查阅上架说明中引用的文档。 - ## 开发 -```bash -# 安装依赖 -pnpm install +| 命令 | 作用 | +| --- | --- | +| `pnpm dev` | 监听文件变化并构建到 `templates/` | +| `pnpm build` | 构建模板与静态资源，自动合并历史哈希资源 | +| `pnpm snapshot` | 把本次构建的哈希资源快照进 `compat/assets`（发版前执行） | +| `pnpm audit:external` | 外部资源、隐私与 README 链接审计（打包时自动执行） | +| `pnpm smoke` | 点击特效脚本与 JSON-LD 冒烟测试 | +| `pnpm package` | 打包 `dist/warm-island-.zip` | +| `pnpm release` | 等价于 `build` → `snapshot` → `package` | -# 开发模式（监听文件变化，自动构建到 templates/） -pnpm dev - -# 构建（输出到 templates/，并自动合并历史版本的静态资源） -pnpm build - -# 把本次构建的哈希资源快照进 compat/assets（发版前必做） -pnpm snapshot - -# 外部资源 / 隐私 / README 链接审计（打包时也会自动执行） -pnpm audit:external - -# 打包 dist/warm-island-.zip -pnpm package - -# 点击特效脚本 + 内容渲染安全（JSON-LD）冒烟测试 -pnpm smoke -``` - -发版流程：`pnpm release`（等价于 `pnpm build` → `pnpm snapshot` → `pnpm package`）， -并把 `compat/assets` 的新增文件一起提交。`pnpm package` 会校验模板、资源目录与版本号一致性， -并执行外部资源审计（禁止第三方预连接、远程脚本、动态加载、无效 README 链接、重复大图）， -任一不通过都会直接报错，避免打出不合规或不含 `templates/` 的空壳安装包。 +发版执行 `pnpm release`，并把 `compat/assets` 的新增文件一起提交。`pnpm package` 会校验模板、资源目录与版本号一致性并执行外部资源审计，任一不通过即报错。 ### 目录结构 @@ -260,12 +191,13 @@ pnpm smoke ### 主题开发注意事项 -- **静态资源文件名带内容哈希**：升级后旧文件被删除，被缓存的 HTML 仍会请求旧文件名并触发 500， - 所以每个版本的哈希文件都要留一份（见 `compat/assets` 与 `pnpm snapshot`） -- **不得引入远程脚本 / 样式 / 字体 / 预连接**：所有第三方资源必须自托管并标注许可，`pnpm package` 会拦截回归 -- **不得把站点内容用 `th:utext` 拼进 `