> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 安装与升级

> 适用版本 ≥ 2.0.0 ｜ 后台路径：主题

## 环境要求

| 项目   | 要求                                                     |
| ---- | ------------------------------------------------------ |
| Halo | ≥ 2.25.0                                               |
| 浏览器  | 近两年内的 Chrome / Edge / Safari / Firefox                 |
| 可选插件 | 见 [插件兼容清单](/ethereal/advanced/plugins.md)，不装也能正常使用核心功能 |

## 安装

### 方式一：应用市场（推荐）

1. 后台「应用市场」搜索 **Ethereal**
2. 点击安装，安装完成后回到「主题」页面启用

### 方式二：手动上传

1. 从 [Releases](https://github.com/AloneNanNan/halo-theme-ethereal/releases) 下载最新的 `.zip` 主题包
2. 后台「主题 → 安装 → 上传主题」，选择该 zip
3. 安装完成后启用

> 上传的必须是**主题包本体**（zip 根目录包含 `theme.yaml`）。直接把源码仓库打包上传会因缺少构建产物而无法使用。

### 启用后

主题启用即刻生效，无需重启 Halo。首次使用建议按这个顺序配置：

1. [Banner 样式](/ethereal/appearance/banner-style.md)：换成自己的图片或视频
2. [菜单栏](/ethereal/appearance/navbar.md)：挂上站点菜单
3. [侧边栏](/ethereal/sidebar/overview.md)：删掉示例小组件，按需添加
4. [页脚](/ethereal/site/footer.md)：备案号与链接
5. [扩展页面](/ethereal/content/extend-pages.md)：创建关于、友链等页面

## 升级

1. 后台「主题」页面会提示可用更新，点击升级即可
2. 或手动上传新版本 zip 覆盖安装
3. 升级完成后强刷一次前台页面（macOS `Cmd + Shift + R`，Windows `Ctrl + F5`），避免旧 CSS / JS 缓存

**设置会不会丢**：同一分组名下的设置会保留。但版本升级如果调整了设置分组（例如 2.0 把「基础设置」拆分到「布局设置」与「样式设置」），被移动的那部分设置会回落默认值，需要重新确认。跨大版本升级前，建议先记录当前设置，升级后核对分组是否有变动。

## 回滚

- 升级前保留上一版本的 zip，出问题时上传旧包覆盖即可回滚
- 回滚后若设置项结构不同，同样需要重新确认受影响的分组
- 主题回滚不影响文章、评论等内容数据

## 安装失败排查

| 现象         | 可能原因            | 处理                                  |
| ---------- | --------------- | ----------------------------------- |
| 提示版本不兼容    | Halo 低于 2.25.0  | 先升级 Halo                            |
| 上传失败 / 413 | 反向代理限制了上传体积     | 调大 Nginx `client_max_body_size` 后重试 |
| 启用后前台白屏    | 缓存未刷新、或其它插件注入冲突 | 强刷；切换到默认主题对比；查看 Halo 日志             |
| 启用后样式错乱    | 浏览器缓存了旧资源       | 强刷；CDN 场景下刷新缓存                      |
| 页面 404     | 路由前缀 / 伪静态配置    | 检查 Halo 的站点地址与反向代理配置                |

排查顺序建议：**先强刷 → 再切默认主题对比 → 再看 Halo 日志**。能稳定复现时，带上 Halo 版本、主题版本与报错日志提 Issue。