Logo

菜单

易君召
易君召
发布于 2026-05-25 / 47 阅读
0
0

uni-halo 完整安装部署指南 全程实战操作（微信小程序版）

我在一个月前使用Halo开源版本搭建了个人博客，最近在研究如何移植到手机端，最好是有国内开源平台直接使用，不需要自己花费精力。

经过网上搜索与对比发现，uni-halo是一款搭配Halo的利器，比较符合我的需求。uni-halo 是基于 uni-app + Halo 2.x API 开发的开源多端博客应用，主要支持微信小程序和 APP 平台。官网https://uni-halo.925i.cn/ 设计风格唯美，开源作者小莫唐尼也非常热心，秒级响应速度，周末时间通宵搞定halo新版本API调整优化代码，很快发布优化新版本。

以下是从0到1的完整部署步骤。

一、前置条件

  • 已成功部署 Halo 2.17.0 及以上版本 的博客系统（必须）

  • 拥有一个已备案的域名并配置了 HTTPS（小程序要求）

  • 服务器端口已开放（默认 8090，或你自定义的 Halo 端口）

二、账号准备

2.1 注册微信小程序账号

  1. 访问 微信公众平台

  2. 选择 "小程序" 类型进行注册

  3. 完成实名认证（个人 / 企业均可）

  4. 登录小程序后台，在 "开发"->"开发设置" 中获取 AppID (小程序 ID) 并保存

2.2 注册 DCloud 开发者账号

  1. 访问 DCloud 开发者中心

  2. 完成注册并登录

  3. 此账号用于登录 HBuilder X 开发工具和编译 uni-app 项目

三、开发环境搭建

3.1 安装 Node.js

  • 推荐版本：14.x、16.x 或 18.x

  • 下载地址：Node.js 官网

  • 安装完成后，在终端输入 node -v 和 npm -v 验证是否成功

3.2 安装 HBuilder X

  • 下载地址：HBuilder X 官网

  • 选择 "App 开发版" 下载安装

  • 打开 HBuilder X，使用刚才注册的 DCloud 账号登录

3.3 安装微信开发者工具

  • 下载地址：微信开发者工具官网

  • 安装完成后，在 HBuilder X 中配置关联：

    1. 打开 HBuilder X，点击顶部菜单 "工具"->"设置"->"运行配置"

    2. 找到 "微信开发工具路径"，选择微信开发者工具的安装目录

    3. 点击 "应用" 保存

四、获取 uni-halo 源码

4.1 下载源码

有两种方式获取源码：

方式一：直接下载 ZIP 包（推荐新手）

方式二：Git 克隆（推荐开发者）

# Gitee
git clone https://gitee.com/ialley-workshop-open/uni-halo.git

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

4.2 导入源码到 HBuilder X

  1. 解压下载的 ZIP 包

  2. 打开 HBuilder X，点击左上角 "文件"->"导入"->"从本地文件夹导入"

  3. 选择解压后的 uni-halo 文件夹，点击 "确定"

4.3 安装项目依赖

  1. 在 HBuilder X 的项目管理器中，右键点击 uni-halo 项目根目录

  2. 选择 "在终端打开"

  3. 在终端中输入以下命令安装依赖：

npm install

  1. 等待依赖安装完成（可能需要几分钟）

注意：运行npm install后，确保项目代码中出现了node_modules文件夹，这是npm安装的依赖包，如果没有的话，需要重新运行该命令。

五、安装并配置 UniHalo 配套插件

uni-halo 需要在 Halo 后台安装配套的配置插件才能正常工作。

5.1 安装插件

方式一：通过 Halo 应用市场安装（推荐）

  1. 登录你的 Halo 后台管理系统

  2. 进入 "插件"->"应用市场"

  3. 搜索 "UniHalo 配置"或“uni-halo”

  4. 点击 "安装"，等待安装完成

  5. 安装完成后，点击 "启用" 插件

采用这种方式比较简单，尤其对应没有技术背景的小白用户特别好用

方式二：手动安装

  1. 访问 插件发布页

  2. 下载最新版本的 JAR 包

  3. 回到 Halo 后台，进入 "插件"->"已安装"

  4. 点击右上角 "上传"，选择下载的 JAR 包

  5. 上传完成后启用插件

5.2 生成 Halo 个人令牌

  1. 在 Halo 后台，点击右上角头像，选择 "个人中心"

  2. 点击上侧菜单 "个人令牌"

  3. 点击 "新建" 按钮

  4. 填写令牌名称（如 "uni-halo"），设置过期时间（建议长期有效）

  5. 重要：只勾选以下读取权限（避免权限泄露）：

    • 文章：读取

    • 分类：读取

    • 标签：读取

    • 瞬间：读取

    • 友情链接：读取

    • 评论：读取和创建

    • 用户：读取

  6. 点击 "提交" 生成令牌

  7. 立即复制生成的令牌（只会显示一次）

5.3 配置 UniHalo 插件

  1. 在 Halo 后台，进入 "插件"->"已安装"

  2. 找到 "UniHalo 配置" 插件，点击 "设置"

  3. 在 "基本配置"->"Token 配置" 中，粘贴刚才复制的个人令牌

  4. 依次配置其他选项：

    • 基本配置：文章详情版权、评论开关、免责声明等

    • 应用配置：应用名称、启动页面等

    • 我的配置：博主头像、昵称、简介、社交链接等

    • 页面配置：首页轮播图、导航栏等

    • 图片配置：默认图片地址

  5. 所有配置完成后，点击 "保存"

六、修改 uni-halo 前端配置

6.1 修改基础 API 地址

  1. 在 HBuilder X 中，打开项目根目录下的 config/uhalo.config.js 文件

  2. 修改 BASE_API 为你的 Halo 博客域名（必须以 https 开头，不要加末尾斜杠）：

export default {
  // 你的Halo博客域名
  BASE_API: "https://your-halo-domain.com",
  
  // 其他配置保持默认即可
  ...
}

6.2 修改微信小程序 AppID

  1. 在 HBuilder X 中，点击顶部菜单 "运行"->"运行到小程序模拟器"->"微信开发者工具"

  2. 第一次运行会提示你输入微信小程序 AppID

  3. 输入你在微信公众平台获取的 AppID，点击 "确定"

  4. 或者直接修改 manifest.json 文件：

    • 打开 manifest.json

    • 切换到 "微信小程序" 选项卡

    • 在 "AppID" 输入框中填写你的小程序 AppID

七、本地运行测试

  1. 在 HBuilder X 中，点击顶部菜单 "运行"->"运行到小程序模拟器"->"微信开发者工具"

  2. HBuilder X 会自动编译项目并打开微信开发者工具

  3. 在微信开发者工具中，你可以预览小程序的效果

  4. 测试所有功能是否正常：

    • 首页文章列表是否显示

    • 文章详情是否能打开

    • 评论功能是否正常

    • 瞬间、友情链接等页面是否正常

八、发布微信小程序

8.1 配置小程序合法域名

  1. 登录微信公众平台小程序后台

  2. 进入 "开发"->"开发管理"->"开发设置"->"服务器域名"

  3. 点击 "修改"，在 "request 合法域名" 中添加你的 Halo 博客域名（必须是 HTTPS）

  4. 点击 "保存并提交"

8.2 编译发布

  1. 在 HBuilder X 中，点击顶部菜单 "发行"->"小程序 - 微信"

  2. 填写小程序名称和 AppID（如果之前已经填过会自动填充）

  3. 点击 "发行"，HBuilder X 会自动编译项目

  4. 编译完成后，会自动打开微信开发者工具

跳转到如下弹框

8.3 上传代码

  1. 在微信开发者工具中，点击右上角 "上传" 按钮

  2. 填写版本号和项目备注

  3. 点击 "上传"，等待上传完成

8.4 提交审核并发布

  1. 登录微信公众平台小程序后台

  2. 进入 "管理"->"版本管理"

  3. 在 "开发版本" 中找到刚才上传的版本

  4. 点击 "提交审核"

  5. 按照提示填写审核信息：

    • 功能页面截图

    • 小程序功能说明

    • 测试账号（如果需要）

  6. 提交后等待微信审核（通常 1-3 个工作日）

  7. 审核通过后，在 "审核版本" 中点击 "发布"

  8. 发布成功后，用户就可以通过搜索小程序名称或扫描小程序码访问你的博客小程序了

九、常见问题与解决方案

9.1 无法获取数据

  • 检查 Halo 博客是否正常运行

  • 检查 uhalo.config.js 中的 BASE_API 是否正确

  • 检查微信开发者工具是否开启了 "不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书"（开发阶段）

  • 检查 Halo 后台的 UniHalo 插件是否已启用并正确配置了令牌

9.2 令牌权限不足

  • 确保令牌只勾选了必要的读取权限

  • 重新生成令牌并在插件配置中更新

9.3 小程序审核不通过

  • 检查小程序内容是否符合微信平台规范

  • 确保所有网络请求都使用了 HTTPS

  • 确保已在小程序后台配置了合法域名

  • 个人主体小程序不要包含商业性质的内容

十、其他平台发布

uni-halo 理论上支持编译为其他平台的应用：

  • APP：在 HBuilder X 中点击 "发行"->"原生 App - 云打包"

  • H5：在 HBuilder X 中点击 "发行"->"网站 - H5 手机版"

  • 其他小程序：如支付宝、百度小程序等，需要在 HBuilder X 中配置对应平台的信息

注意：其他平台可能需要额外的配置和适配，具体请参考 uni-app 官方文档。

最后，再次感谢uni-halo的开源作者小莫唐尼，这样开源无畏、快速响应的精神值得我们学习。

原文链接 https://www.yijunzhao.cn/archives/uni-halo-wan-zheng-an-zhuang-bu-shu-zhi-nan-wei-xin-xiao-cheng-xu-ban

欢迎访问 小易撩挨踢

https://www.yijunzhao.cn/

小龙虾OpenClaw不火了？国民...
99% 站长都搞错的真相：备案只认...

评论