# Uni-Halo 微信小程序开发实战指南

> 基于 uni-app + Halo 2.x 构建现代化开源博客小程序，一套代码，多端运行

---

## 一、什么是 Uni-Halo

Uni-Halo 是一个基于 uni-app 跨端框架，对接 Halo 2.x 博客系统 API 的开源移动端应用。它由开发者小莫唐尼维护，遵循 AGPL-3.0 协议免费开源，目前已迭代至 v2.0。

它的核心价值在于：让你用 一套代码 同时编译成微信小程序、Android/iOS App、H5 网页。如果你已经搭建了 Halo 博客，Uni-Halo 就是它的移动端解决方案。

- GitHub：[ialley-workshop-open/uni-halo](https://github.com/ialley-workshop-open/uni-halo)（139+ Stars）

- 官方文档：[uni-halo.925i.cn](https://uni-halo.925i.cn/)

- 交流群：QQ 632969367

---

## 二、技术栈与架构

Uni-Halo 的技术选型非常朴实——没有花哨的框架，而是选择了生态成熟的组合：

| 层级 | 技术 | 说明 |

|------|------|------|

| 前端框架 | uni-app（Vue） | DCloud 出品的跨端框架，一套代码编多端 |

| 后端 | Halo 2.x | Java 开发的现代化博客/CMS 系统 |

| UI 组件库 | tm-vuetify | 基于 uni-app 的 UI 框架 |

| 富文本渲染 | mp-html | 专为小程序优化的富文本组件 |

| 插件系统 | UniHalo 配置插件 | 在 Halo 后台动态管理小程序配置 |

项目代码构成以 Vue 为主（57%），配合 JavaScript（31%），整体结构清晰，非常适合作为二次开发的学习样本。

---

## 三、部署前的准备工作

在动手之前，有几件事必须提前完成：

### 3.1 条件清单

1. Halo 2.0 站点：已部署并可通过 https://你的域名 访问，需完成 ICP 备案 + SSL 证书

2. 微信小程序账号：在 [mp.weixin.qq.com](https://mp.weixin.qq.com) 注册

3. DCloud 开发者账号：在 [dev.dcloud.net.cn](https://dev.dcloud.net.cn) 注册

4. 本地开发工具：HBuilder X + 微信开发者工具

5. Node.js 14+ 环境：用于安装依赖

### 3.2 安装 Halo 插件

在 Halo 后台需要安装以下插件：

| 插件 | 功能 |

|------|------|

| UniHalo 配置 | 核心配置插件，必装 |

| 评论组件 | 提供用户评论能力 |

| 搜索组件 | 文章和瞬间搜索 |

| 链接管理 | 友情链接展示 |

| 图库管理 | 图片图库展示 |

| 瞬间插件 | 轻量日记式内容 |

> 所有插件均可在 Halo 应用市场搜索安装。

### 3.3 创建个人令牌

在 Halo 后台的 个人中心 → 个人令牌 中新建一个令牌，权限授予方式选择 "仅查看"，勾选以下项目：

- 配置管理（UniHalo）

- 评论查看

- 链接查看

- 图库查看

- 瞬间查看

然后将生成的令牌填入 UniHalo 配置插件 的 Token 配置项中。

---

## 四、开发环境搭建

### 4.1 工具安装

| 工具 | 下载地址 |

|------|---------|

| HBuilder X | [dcloud.io/hbuilderx.html](https://www.dcloud.io/hbuilderx.html) |

| 微信开发者工具 | [developers.weixin.qq.com](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html) |

| Node.js 14+ | [nodejs.org](https://nodejs.org/zh-cn/download) |

### 4.2 关键配置

安装好之后，做两件事：

1. HBuilder X 登录 DCloud 账号：用于调用微信开发者工具和打包

2. 关联微信开发者工具路径：HBuilder X → 工具 → 设置 → 运行配置 → 微信开发者工具路径，指向安装目录下的 cli.bat（Windows）或 wechatdevtools.app/Contents/MacOS/cli（macOS）

### 4.3 获取源码并启动

```bash

# 克隆仓库

git clone https://github.com/ialley-workshop-open/uni-halo.git

# 进入项目目录

cd uni-halo

# 安装依赖

npm install

```

然后在 HBuilder X 中：**文件 → 导入 → 从本地文件夹导入**，选择刚刚克隆的项目。

---

## 五、核心配置

### 5.1 修改 AppID（manifest.json）

需要在 manifest.json 中修改两个 AppID：

- uni-app 的 AppID：在 HBuilder X 项目属性中生成

- 微信小程序 AppID：登录微信小程序后台获取

### 5.2 配置博客域名

编辑 config/uhalo.config.js，将 BASE_API 的值替换为你的 Halo 博客域名：

```javascript

BASE_API: 'https://yourdomain.com'

```

### 5.3 配置微信后台服务器域名

登录微信小程序后台 → 管理 → 开发管理 → 服务器域名，在以下三项中均添加你的博客域名：

- request 合法域名

- uploadFile 合法域名

- downloadFile 合法域名

### 5.4 审核模式（Mock 数据）

小程序提审时，如果真实内容包含分享/社交元素可能导致拒审。Uni-Halo 贴心地提供了 审核模式，通过 config/unihalo.mock.json 配置假数据，让审核人员看到的是固定内容而非你的真实博客。

> 注意：json 文件中不允许注释，配置时需删除 // xxx 之类的注释。

如果你博客内容本身很少，也可以不开启审核模式直接提审。

---

## 六、本地预览与发布

### 6.1 本地预览

在 HBuilder X 中：**运行 → 运行到小程序 → 微信开发者工具**。

编译完成后，微信开发者工具会自动打开。点击 预览 按钮，扫码在手机上查看效果。

### 6.2 上传版本

确认预览无误后，在微信开发者工具点击 上传，填写版本号和备注，提交到微信后台。

### 6.3 体验版

上传成功后，登录微信小程序后台 → 管理 → 版本管理，在"开发版本"右侧点击 体验版，生成二维码分享给测试人员。

### 6.4 提交审核

在"开发版本"点击 提交审核，填写审核信息。作者推荐的描述：

> 个人日记小程序，用于记录个人工作和生活

这个描述比较稳妥——个人资质下更容易通过。

### 6.5 发布上线

审核通过后，在"审核版本"点击 发布上线，你的博客小程序就正式上线了。

---

## 七、特色功能：恋爱日记

Uni-Halo 有一个很有意思的特色功能——**恋爱日记模块**：

- 情侣甜蜜相册

- 恋爱记录清单

- 秀恩爱模块

配置方式：在 UniHalo 配置插件中填写"恋爱相册标识"。获取方式如下：

打开 Halo 博客页面 → F12 开发者工具 → 网络 → 图库分类 → 找到 photogroups 请求 → 预览返回数据 → 复制 metadata.name 的值填入配置。

这个功能让 Uni-Halo 不仅是博客小程序，也可以变身为情侣专属的甜蜜记录工具。

---

## 八、项目特点与适合人群

### 谁适合用 Uni-Halo？

- Halo 用户：已经搭建了 Halo 博客，想要一个移动端小程序

- 个人站长：不想从零写小程序，希望快速上线

- uni-app 初学者：想学习一套代码多端编译的实战项目

- 情侣：想做一个专属的恋爱日记应用

### 优势

1. 免费开源：没有任何收费陷阱，可以自由修改

2. 插件化配置：v2.0 引入插件配置，无需修改源码即可调整大部分内容

3. 代码规范：项目结构清晰，注释完善，易于二次开发

4. 多端支持：一份代码 = 小程序 + App + H5

### 局限

- 依赖 Halo 2.x 后端，不能独立运行

- 微信小程序对个人开发者的类目和功能有限制

- 社交/分享功能可能影响审核通过率

---

## 九、总结

Uni-Halo 是一个小而美的开源项目，它解决了 Halo 博客在移动端的呈现问题。从部署流程来看，作者非常贴心地写好了完整的文档，从插件配置到 Mock 数据的审核模式都有考虑。

对于已经拥有 Halo 博客的开发者来说，花一下午时间就能让自己的博客拥有一个微信小程序，性价比非常高。如果你是 uni-app 的初学者，这个项目也是很好的实战学习材料——代码规范、架构清晰，文档也完善。

> 项目地址：[GitHub](https://github.com/ialley-workshop-open/uni-halo) | 官方文档：[uni-halo.925i.cn](https://uni-halo.925i.cn/) | QQ 交流群：632969367

---

本文基于 uni-halo 官方文档撰写，信息截至 v2.0.10（2025-08-29）。