uni-halo 完整安裝部署指南 全程實(shí)戰(zhàn)操作（微信小程序版）

我在一個(gè)月前使用Halo開(kāi)源版本搭建了個(gè)人博客，最近在研究如何移植到手機(jī)端，最好是有國(guó)內(nèi)開(kāi)源平臺(tái)直接使用，不需要自己花費(fèi)精力。

經(jīng)過(guò)網(wǎng)上搜索與對(duì)比發(fā)現(xiàn)，uni-halo是一款搭配Halo的利器，比較符合我的需求。uni-halo 是基于 uni-app + Halo 2.x API 開(kāi)發(fā)的開(kāi)源多端博客應(yīng)用，主要支持微信小程序和 APP 平臺(tái)。官網(wǎng)https://uni-halo.925i.cn/ 設(shè)計(jì)風(fēng)格唯美，開(kāi)源作者小莫唐尼也非常熱心，秒級(jí)響應(yīng)速度，周末時(shí)間通宵搞定halo新版本API調(diào)整優(yōu)化代碼，很快發(fā)布優(yōu)化新版本。

以下是從0到1的完整部署步驟。

一、前置條件

  • 已成功部署 Halo 2.17.0 及以上版本 的博客系統(tǒng)（必須）

  • 擁有一個(gè)已備案的域名并配置了 HTTPS（小程序要求）

  • 服務(wù)器端口已開(kāi)放（默認(rèn) 8090，或你自定義的 Halo 端口）

二、賬號(hào)準(zhǔn)備

2.1 注冊(cè)微信小程序賬號(hào)

  1. 訪問(wèn) 微信公眾平臺(tái)

  2. 選擇 "小程序" 類型進(jìn)行注冊(cè)

  3. 完成實(shí)名認(rèn)證（個(gè)人 / 企業(yè)均可）

  4. 登錄小程序后臺(tái)，在 "開(kāi)發(fā)"->"開(kāi)發(fā)設(shè)置" 中獲取 AppID (小程序 ID) 并保存

2.2 注冊(cè) DCloud 開(kāi)發(fā)者賬號(hào)

  1. 訪問(wèn) DCloud 開(kāi)發(fā)者中心

  2. 完成注冊(cè)并登錄

  3. 此賬號(hào)用于登錄 HBuilder X 開(kāi)發(fā)工具和編譯 uni-app 項(xiàng)目

三、開(kāi)發(fā)環(huán)境搭建

3.1 安裝 Node.js

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

  • 下載地址：Node.js 官網(wǎng)

  • 安裝完成后，在終端輸入 node -v 和 npm -v 驗(yàn)證是否成功

3.2 安裝 HBuilder X

  • 下載地址：HBuilder X 官網(wǎng)

  • 選擇 "App 開(kāi)發(fā)版" 下載安裝

  • 打開(kāi) HBuilder X，使用剛才注冊(cè)的 DCloud 賬號(hào)登錄

3.3 安裝微信開(kāi)發(fā)者工具

  • 下載地址：微信開(kāi)發(fā)者工具官網(wǎng)

  • 安裝完成后，在 HBuilder X 中配置關(guān)聯(lián)：

    1. 打開(kāi) HBuilder X，點(diǎn)擊頂部菜單 "工具"->"設(shè)置"->"運(yùn)行配置"

    2. 找到 "微信開(kāi)發(fā)工具路徑"，選擇微信開(kāi)發(fā)者工具的安裝目錄

    3. 點(diǎn)擊 "應(yīng)用" 保存

四、獲取 uni-halo 源碼

4.1 下載源碼

有兩種方式獲取源碼：

方式一：直接下載 ZIP 包（推薦新手）

方式二：Git 克?。ㄍ扑]開(kāi)發(fā)者）

# 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 導(dǎo)入源碼到 HBuilder X

  1. 解壓下載的 ZIP 包

  2. 打開(kāi) HBuilder X，點(diǎn)擊左上角 "文件"->"導(dǎo)入"->"從本地文件夾導(dǎo)入"

  3. 選擇解壓后的 uni-halo 文件夾，點(diǎn)擊 "確定"

4.3 安裝項(xiàng)目依賴

  1. 在 HBuilder X 的項(xiàng)目管理器中，右鍵點(diǎn)擊 uni-halo 項(xiàng)目根目錄

  2. 選擇 "在終端打開(kāi)"

  3. 在終端中輸入以下命令安裝依賴：

npm install

  1. 等待依賴安裝完成（可能需要幾分鐘）

注意：運(yùn)行npm install后，確保項(xiàng)目代碼中出現(xiàn)了node_modules文件夾，這是npm安裝的依賴包，如果沒(méi)有的話，需要重新運(yùn)行該命令。

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

uni-halo 需要在 Halo 后臺(tái)安裝配套的配置插件才能正常工作。

5.1 安裝插件

方式一：通過(guò) Halo 應(yīng)用市場(chǎng)安裝（推薦）

  1. 登錄你的 Halo 后臺(tái)管理系統(tǒng)

  2. 進(jìn)入 "插件"->"應(yīng)用市場(chǎng)"

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

  4. 點(diǎn)擊 "安裝"，等待安裝完成

  5. 安裝完成后，點(diǎn)擊 "啟用" 插件

采用這種方式比較簡(jiǎn)單，尤其對(duì)應(yīng)沒(méi)有技術(shù)背景的小白用戶特別好用

方式二：手動(dòng)安裝

  1. 訪問(wèn) 插件發(fā)布頁(yè)

  2. 下載最新版本的 JAR 包

  3. 回到 Halo 后臺(tái)，進(jìn)入 "插件"->"已安裝"

  4. 點(diǎn)擊右上角 "上傳"，選擇下載的 JAR 包

  5. 上傳完成后啟用插件

5.2 生成 Halo 個(gè)人令牌

  1. 在 Halo 后臺(tái)，點(diǎn)擊右上角頭像，選擇 "個(gè)人中心"

  2. 點(diǎn)擊上側(cè)菜單 "個(gè)人令牌"

  3. 點(diǎn)擊 "新建" 按鈕

  4. 填寫令牌名稱（如 "uni-halo"），設(shè)置過(guò)期時(shí)間（建議長(zhǎng)期有效）

  5. 重要：只勾選以下讀取權(quán)限（避免權(quán)限泄露）：

    • 文章：讀取

    • 分類：讀取

    • 標(biāo)簽：讀取

    • 瞬間：讀取

    • 友情鏈接：讀取

    • 評(píng)論：讀取和創(chuàng)建

    • 用戶：讀取

  6. 點(diǎn)擊 "提交" 生成令牌

  7. 立即復(fù)制生成的令牌（只會(huì)顯示一次）

5.3 配置 UniHalo 插件

  1. 在 Halo 后臺(tái)，進(jìn)入 "插件"->"已安裝"

  2. 找到 "UniHalo 配置" 插件，點(diǎn)擊 "設(shè)置"

  3. 在 "基本配置"->"Token 配置" 中，粘貼剛才復(fù)制的個(gè)人令牌

  4. 依次配置其他選項(xiàng)：

    • 基本配置：文章詳情版權(quán)、評(píng)論開(kāi)關(guān)、免責(zé)聲明等

    • 應(yīng)用配置：應(yīng)用名稱、啟動(dòng)頁(yè)面等

    • 我的配置：博主頭像、昵稱、簡(jiǎn)介、社交鏈接等

    • 頁(yè)面配置：首頁(yè)輪播圖、導(dǎo)航欄等

    • 圖片配置：默認(rèn)圖片地址

  5. 所有配置完成后，點(diǎn)擊 "保存"

六、修改 uni-halo 前端配置

6.1 修改基礎(chǔ) API 地址

  1. 在 HBuilder X 中，打開(kāi)項(xiàng)目根目錄下的 config/uhalo.config.js 文件

  2. 修改 BASE_API 為你的 Halo 博客域名（必須以 https 開(kāi)頭，不要加末尾斜杠）：

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

6.2 修改微信小程序 AppID

  1. 在 HBuilder X 中，點(diǎn)擊頂部菜單 "運(yùn)行"->"運(yùn)行到小程序模擬器"->"微信開(kāi)發(fā)者工具"

  2. 第一次運(yùn)行會(huì)提示你輸入微信小程序 AppID

  3. 輸入你在微信公眾平臺(tái)獲取的 AppID，點(diǎn)擊 "確定"

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

    • 打開(kāi) manifest.json

    • 切換到 "微信小程序" 選項(xiàng)卡

    • 在 "AppID" 輸入框中填寫你的小程序 AppID

七、本地運(yùn)行測(cè)試

  1. 在 HBuilder X 中，點(diǎn)擊頂部菜單 "運(yùn)行"->"運(yùn)行到小程序模擬器"->"微信開(kāi)發(fā)者工具"

  2. HBuilder X 會(huì)自動(dòng)編譯項(xiàng)目并打開(kāi)微信開(kāi)發(fā)者工具

  3. 在微信開(kāi)發(fā)者工具中，你可以預(yù)覽小程序的效果

  4. 測(cè)試所有功能是否正常：

    • 首頁(yè)文章列表是否顯示

    • 文章詳情是否能打開(kāi)

    • 評(píng)論功能是否正常

    • 瞬間、友情鏈接等頁(yè)面是否正常

八、發(fā)布微信小程序

8.1 配置小程序合法域名

  1. 登錄微信公眾平臺(tái)小程序后臺(tái)

  2. 進(jìn)入 "開(kāi)發(fā)"->"開(kāi)發(fā)管理"->"開(kāi)發(fā)設(shè)置"->"服務(wù)器域名"

  3. 點(diǎn)擊 "修改"，在 "request 合法域名" 中添加你的 Halo 博客域名（必須是 HTTPS）

  4. 點(diǎn)擊 "保存并提交"

8.2 編譯發(fā)布

  1. 在 HBuilder X 中，點(diǎn)擊頂部菜單 "發(fā)行"->"小程序 - 微信"

  2. 填寫小程序名稱和 AppID（如果之前已經(jīng)填過(guò)會(huì)自動(dòng)填充）

  3. 點(diǎn)擊 "發(fā)行"，HBuilder X 會(huì)自動(dòng)編譯項(xiàng)目

  4. 編譯完成后，會(huì)自動(dòng)打開(kāi)微信開(kāi)發(fā)者工具

跳轉(zhuǎn)到如下彈框

8.3 上傳代碼

  1. 在微信開(kāi)發(fā)者工具中，點(diǎn)擊右上角 "上傳" 按鈕

  2. 填寫版本號(hào)和項(xiàng)目備注

  3. 點(diǎn)擊 "上傳"，等待上傳完成

8.4 提交審核并發(fā)布

  1. 登錄微信公眾平臺(tái)小程序后臺(tái)

  2. 進(jìn)入 "管理"->"版本管理"

  3. 在 "開(kāi)發(fā)版本" 中找到剛才上傳的版本

  4. 點(diǎn)擊 "提交審核"

  5. 按照提示填寫審核信息：

    • 功能頁(yè)面截圖

    • 小程序功能說(shuō)明

    • 測(cè)試賬號(hào)（如果需要）

  6. 提交后等待微信審核（通常 1-3 個(gè)工作日）

  7. 審核通過(guò)后，在 "審核版本" 中點(diǎn)擊 "發(fā)布"

  8. 發(fā)布成功后，用戶就可以通過(guò)搜索小程序名稱或掃描小程序碼訪問(wèn)你的博客小程序了

九、常見(jiàn)問(wèn)題與解決方案

9.1 無(wú)法獲取數(shù)據(jù)

  • 檢查 Halo 博客是否正常運(yùn)行

  • 檢查 uhalo.config.js 中的 BASE_API 是否正確

  • 檢查微信開(kāi)發(fā)者工具是否開(kāi)啟了 "不校驗(yàn)合法域名、web-view（業(yè)務(wù)域名）、TLS 版本以及 HTTPS 證書(shū)"（開(kāi)發(fā)階段）

  • 檢查 Halo 后臺(tái)的 UniHalo 插件是否已啟用并正確配置了令牌

9.2 令牌權(quán)限不足

  • 確保令牌只勾選了必要的讀取權(quán)限

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

9.3 小程序?qū)徍瞬煌ㄟ^(guò)

  • 檢查小程序內(nèi)容是否符合微信平臺(tái)規(guī)范

  • 確保所有網(wǎng)絡(luò)請(qǐng)求都使用了 HTTPS

  • 確保已在小程序后臺(tái)配置了合法域名

  • 個(gè)人主體小程序不要包含商業(yè)性質(zhì)的內(nèi)容

十、其他平臺(tái)發(fā)布

uni-halo 理論上支持編譯為其他平臺(tái)的應(yīng)用：

  • APP：在 HBuilder X 中點(diǎn)擊 "發(fā)行"->"原生 App - 云打包"

  • H5：在 HBuilder X 中點(diǎn)擊 "發(fā)行"->"網(wǎng)站 - H5 手機(jī)版"

  • 其他小程序：如支付寶、百度小程序等，需要在 HBuilder X 中配置對(duì)應(yīng)平臺(tái)的信息

注意：其他平臺(tái)可能需要額外的配置和適配，具體請(qǐng)參考 uni-app 官方文檔。

最后，再次感謝uni-halo的開(kāi)源作者小莫唐尼，這樣開(kāi)源無(wú)畏、快速響應(yīng)的精神值得我們學(xué)習(xí)。

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

歡迎訪問(wèn) 小易撩挨踢

https://www.yijunzhao.cn/
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書(shū)系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容