Halo-Theme-Ethereal
一款基于 halo-theme-fuwari 二次开发
为 Halo 2.x 打造的现代博客主题
预览：楠枝小笺
介绍
Ethereal 是基于 halo-theme-fuwari（原版 Fuwari 的 Halo 移植版）深度二次开发的博客主题。在保留原有清爽调性的基础上，新增了大量功能和视觉改进，感谢原作的开源贡献。
主题灵感来源于 Firefly 的清新美学，融合了多种现代 UI 趋势，希望能为 Halo 用户提供一个好看且实用的主题选择。感谢 Firefly 的开源贡献。
主题使用AI辅助开发。
主题亮点
- 三栏/两栏布局随心切换 — 左侧栏 + 主内容区 + 右侧栏，充分利用宽屏空间，信息层级清晰
- 丰富的小组件 — 天气、音乐播放器、一言、站点统计、热门文章、自定义 HTML 等，左右侧边栏栏自由组合搭配
- 模糊混色效果 — 导航栏磨砂玻璃效果，通透有质感
- Banner 居中大标题 — 支持自定义标题/副标题/字号，打字机/文字下坠两种动效，响应式字号缩放
- 卡片 3D 倾斜 — 部分卡片（如友情链接、朋友圈文章等卡片）随鼠标移动产生微妙的 3D 倾斜效果。
- 图片速度优化 — 支持主流 CDN/对象存储的实时图片压缩缩放，大幅降低封面图和正文图片加载体积
- 深色/浅色模式 — 支持跟随系统、手动切换，后台可配置默认配色
功能特性
核心功能
- 三栏 / 两栏布局自由切换
- 卡片化设计，响应式布局
- 深色 / 浅色 / 跟随系统配色
- 自定义主题色（Hue 调节）
- i18n 国际化（中/英）
- 页面过渡动画（Swup）
- 丰富的小组件
- 外链跳转模态框（自定义延迟、域名白名单）
- 图片速度优化（支持阿里云 ESA/OSS、腾讯云 EdgeOne/COS、七牛云、又拍云等主流 CDN 实时压缩）
视觉效果
- 导航栏磨砂玻璃模糊效果
- Banner 波浪动效
- 卡片 3D 鼠标悬停倾斜效果
- 登录认证界面适配
侧边栏组件
| 组件 | 说明 |
|---|---|
| 天气 | 基于腾讯位置服务，自动定位显示天气 |
| 音乐播放器 | 支持网易云、QQ、酷狗等平台歌单/歌曲 |
| 一言 | 随机显示一句名言或短句 |
| 站点统计 | 文章数、标签数、运行天数等 |
| 文章分类 | 分类列表导航 |
| 文章标签 | 标签云导航 |
| 热门文章 | 热度排行 |
| 自定义 HTML | 自由嵌入任意内容 |
页面支持
- 首页
- 文章归档
- 标签列表 & 标签详情
- 分类列表 & 分类详情
- 图库展示（插件）
- 瞬间 / 说说（插件）
- 友情链接（插件）
- 朋友圈（插件）
- 装备展示（插件）
- 自定义页面
插件支持
Ethereal 与以下 Halo 插件深度集成，建议搭配使用以获得完整体验：
| 插件 | 市场链接 | 功能 |
|---|---|---|
| 搜索插件 | 应用市场 | 文章全文搜索 |
| 评论插件 | 应用市场 | 文章评论系统 |
| 瞬间插件 | 应用市场 | 瞬间/说说功能 |
| 图库插件 | 应用市场 | 图库展示 |
| 链接管理插件 | 应用市场 | 友情链接管理 & 朋友圈 |
| 自助提交友链（暂时移除支持） | 应用市场 | 访客自助提交友链 |
| 装备管理 | 应用市场 | 装备展示 |
外部服务依赖
本主题以下功能依赖外部第三方服务，请在使用前了解：
| 功能 | 外部服务 | 说明 |
|---|---|---|
| 天气小组件 | 腾讯位置服务 | 需用户自行申请 WebService API Key（免费注册），用于 IP 定位和天气数据查询 |
| 音乐播放器 | Meting | 默认使用 Meting 公共 API 获取网易云/QQ/酷狗等平台的歌单歌曲数据，支持在设置中替换为自建 API |
| 一言小组件 | 一言开发者中心 | 随机获取一句名言短句，无需 API Key，支持 5 秒超时和本地 fallback |
以上服务均为可选功能，不影响主题核心的博客浏览体验。天气、音乐、一言小组件需在侧边栏设置中手动添加后才会发起网络请求。
安装
系统要求
- Halo >= 2.25.0
在线安装
- Halo 应用商店搜索 “Ethereal” 即可一键安装
手动安装
- 前往 Releases 下载最新版本的主题包（
.zip） - 进入 Halo 后台 → 主题 → 安装，上传主题包
- 启用主题并进入 设置 进行个性化配置
项目结构
展开查看完整目录结构
halo-theme-ethereal/
├── i18n/ # 国际化翻译文件
│ ├── default.properties # 默认语言（英文）
│ ├── zh_CN.properties # 简体中文
│ └── zh_TW.properties # 繁体中文
├── public/ # 静态资源
│ ├── assets/ # JS 脚本、图片等
│ ├── fragments/ # Halo 页面片段
│ ├── gateway_fragments/ # 网关认证片段
│ └── themes/ # 主题静态资源（图片、CSS 等）
├── screenshot/ # 主题截图
├── src/
│ ├── components/ # 组件
│ │ ├── *.astro # Astro 静态组件（Footer、Navbar、PostCard 等）
│ │ ├── *.svelte # Svelte 交互组件（Search、LightDarkSwitch 等）
│ │ ├── control/ # 控件组件（分页、返回顶部、按钮等）
│ │ ├── misc/ # 杂项组件
│ │ ├── photos/ # 照片相关组件
│ │ └── widget/ # 侧边栏小部件（天气、音乐、目录、统计等）
│ ├── config.ts # 主题配置（运行时）
│ ├── constants/ # 常量定义
│ ├── env.d.ts # 环境类型声明
│ ├── global.d.ts # 全局类型声明
│ ├── layouts/ # 页面布局
│ │ ├── Layout.astro # 根布局
│ │ └── MainGridLayout.astro # 主网格布局
│ ├── pages/ # 页面模板
│ │ ├── index.astro # 首页
│ │ ├── post.astro # 文章页
│ │ ├── archives.astro # 归档页
│ │ ├── tags.astro # 标签列表
│ │ ├── tag.astro # 标签详情
│ │ ├── categories.astro # 分类列表
│ │ ├── category.astro # 分类详情
│ │ ├── photos.astro # 图库列表
│ │ ├── photo.astro # 图库详情
│ │ ├── moment.astro # 瞬间详情
│ │ ├── moments.astro # 瞬间列表
│ │ ├── links.astro # 友情链接
│ │ ├── friends.astro # 朋友圈
│ │ ├── equipments.astro # 装备展示
│ │ └── page.astro # 自定义页面
│ ├── scripts/ # 应用入口脚本
│ │ └── app.ts # 初始化逻辑（主题、滚动条、灯箱等）
│ ├── styles/ # 全局样式
│ ├── types/ # TypeScript 类型定义
│ └── utils/ # 工具函数
├── astro.config.mjs # Astro 构建配置
├── nodemon.json # 开发热更新配置
├── settings.yaml # Halo 主题设置定义
├── svelte.config.js # Svelte 配置
├── theme.yaml # Halo 主题元信息
├── tsconfig.json # TypeScript 配置
├── pnpm-workspace.yaml # pnpm 工作区配置
└── package.json # 项目依赖与脚本
开发
需要 Node.js >= 22.12.0 和 pnpm
# 克隆项目
git clone https://github.com/AloneNanNan/halo-theme-ethereal.git
cd halo-theme-ethereal
# 安装依赖
pnpm install
# 开发模式（监听文件变更自动重建）
pnpm dev
# 构建主题
pnpm build
# 构建并打包为主题安装包
pnpm build:pkg
# 代码格式化
pnpm format
技术栈
| 技术 | 用途 |
|---|---|
| Astro | 静态页面生成与路由 |
| Svelte 5 | 交互组件（Search、LightDarkSwitch） |
| Tailwind CSS 4 | 实用优先的样式框架 |
| TypeScript | 类型安全 |
| Swup | 页面过渡动画 |
| Iconify | 图标系统 |
致谢
- Halo — 优秀的 Java 博客系统
- Fuwari — 原始 Astro 主题，MIT 许可
- halo-theme-fuwari — 原版 Halo 移植主题，MIT 许可
- Firefly — 清新美观的 Astro 静态博客主题模板
- Halo Sig — Halo 社区插件与工具链
许可证
MIT License © 2026 楠南NanNan
本主题基于 halo-theme-fuwari（MIT 许可）二次开发，遵守原始许可证条款。