Uncle小说跨平台部署一站式指南：从源码到多系统安装包构建

Uncle小说是一款开源项目，提供PC版全网小说下载器及阅读器功能，支持目录解析与书源结合，可下载mobi、epub、txt等多种格式文本小说。本文将详细介绍如何为Windows和MacOS系统构建安装包，帮助开发者实现开源项目的跨平台安装包构建与部署。

核心功能概述：Uncle小说能力矩阵

Uncle小说作为一款功能全面的小说管理工具，核心特性包括：

• 多源小说搜索与下载，支持TXT、EPUB、MOBI等格式
• 沉浸式阅读体验，提供多种主题与排版自定义
• 有声小说播放功能，支持文本转语音
• 书架管理系统，支持本地书籍导入与分类
• 自定义书源管理，支持规则配置与扩展

图1：Uncle小说主界面展示，包含书架管理、搜索与分类功能

环境搭建：开发工具链配置流程

目标：配置满足跨平台打包需求的开发环境

环境检测：必备工具校验流程

在开始打包前，需确保系统已安装以下工具：

• JDK（Java开发工具包，版本需11以上）：提供Java程序编译与运行环境
• Gradle 7.0+：项目构建自动化工具
• Git：版本控制工具，用于获取项目源码

通过以下命令验证工具是否安装成功：

# 检查JDK版本
java -version  # 需显示11.0.0以上版本

# 检查Gradle版本
gradle -v      # 需显示7.0以上版本

# 检查Git版本
git --version  # 任意版本均可

源码获取：项目克隆与目录结构解析

使用Git克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/un/uncle-novel
cd uncle-novel

项目核心打包相关目录结构：

• buildSrc/src/main/java/com/unclezs/novel/app/packager/：包含跨平台打包核心逻辑
• app/app.gradle：定义打包任务配置
• app/packager/：存放打包所需资源文件

平台适配指南：系统专属打包方案

Windows平台打包：EXE与MSI安装包构建

目标：生成适用于Windows系统的可执行安装程序

Windows平台提供32位和64位两种打包任务，分别对应不同架构的系统：

# 构建64位Windows安装包（推荐现代系统使用）
./gradlew app:packageWin64

# 构建32位Windows安装包（兼容旧系统）
./gradlew app:packageWin32

注意：Windows打包需要Inno Setup工具支持，需提前安装并配置环境变量。相关配置模板位于app/packager/inno-setup/目录。

Windows打包流程由WindowsPackager.java类实现，主要步骤包括：

1. 编译项目并创建可执行JAR文件
2. 生成EXE格式启动器
3. 构建MSI安装包
4. 生成ZIP压缩分发包

最终产物位于build/packages/目录，包含多种格式的安装文件。

MacOS平台打包：DMG与PKG镜像构建

目标：创建符合MacOS应用标准的安装镜像

MacOS平台打包通过以下命令执行：

# 构建MacOS平台安装包
./gradlew app:packageMac

MacOS打包流程由MacPackager.java类实现，主要步骤包括：

1. 生成.app应用程序束
2. 创建DMG磁盘镜像
3. 构建PKG安装包

注意：在MacOS上进行正式发布可能需要苹果开发者证书进行应用签名，开发测试可跳过此步骤。

平台特性对比：系统打包策略差异分析

不同操作系统由于底层架构和用户习惯差异，采用了不同的打包策略：

特性	Windows平台	MacOS平台
主要安装格式	EXE、MSI	DMG、PKG
应用分发方式	独立安装程序	应用束+镜像
权限管理	用户级安装	系统级验证
快捷方式	开始菜单+桌面	应用程序文件夹
卸载方式	控制面板	拖拽到废纸篓

图2：Uncle小说设置界面，可配置下载路径、格式等打包相关参数

成果验证：安装包功能测试

目标：验证生成的安装包完整性与功能可用性

安装流程测试

成功打包后，在build/packages/目录找到对应系统的安装文件：

• Windows：选择.exe文件双击运行安装向导
• MacOS：打开.dmg文件，将应用拖入应用程序文件夹

核心功能验证清单

安装完成后，启动应用并验证以下核心功能：

1. 界面加载：主窗口正常显示，无布局错乱
2. 小说搜索：可通过搜索框查找小说资源
3. 下载功能：尝试下载一本小说，检查文件是否生成
4. 阅读体验：打开下载的小说，测试翻页、字体调整功能

图3：Uncle小说阅读界面，支持双窗口对比阅读

图4：阅读设置面板，可调整字体、背景色等阅读参数

故障排除指南：常见打包问题解决方案

依赖相关错误

症状：打包过程中出现"找不到依赖"或"版本冲突"提示

解决方案：

# 刷新项目依赖缓存
./gradlew build --refresh-dependencies

Windows打包失败

症状：提示"Inno Setup未找到"或"无法生成EXE"

解决方案：

1. 确认Inno Setup已安装（推荐版本6.0以上）
2. 将Inno Setup安装目录添加到系统PATH环境变量
3. 重启命令行终端后重试打包命令

MacOS签名问题

症状：打包成功但安装时提示"应用已损坏"

解决方案：

1. 开发环境：使用xattr -cr /Applications/Uncle小说.app命令移除扩展属性
2. 生产环境：配置有效的苹果开发者证书进行签名

内存不足错误

症状：打包过程中出现"Out Of Memory"错误

解决方案： 修改gradle.properties文件，增加JVM内存分配：

org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m

总结

本指南详细介绍了Uncle小说开源项目的跨平台打包流程，从环境搭建到各平台特有打包策略，再到安装验证与问题排查，提供了一站式的部署解决方案。通过Gradle自动化构建工具，开发者可以轻松生成适用于Windows和MacOS系统的安装包，为用户提供良好的安装体验。项目的打包逻辑集中在buildSrc/src/main/java/com/unclezs/novel/app/packager/task/PackageTask.java中，可根据实际需求进行定制扩展。