Lumafly：跨平台Hollow Knight模组管理器完全指南

核心功能解析

1.1 智能模组管理系统

Lumafly的核心价值在于其全自动依赖管理和多源模组整合能力。与传统手动复制DLL文件的方式不同，它能自动解析模组间的依赖关系，当你安装"Randomizer"这类复杂模组时，系统会自动检查并安装"Modding API"等前置依赖，避免因缺失组件导致的游戏崩溃。

💡 实用技巧：通过"固定版本"功能锁定关键模组版本，防止更新破坏现有模组组合。在"已安装"标签页右键点击模组即可找到该选项。

graph TD
    A[用户选择模组] --> B{依赖检查}
    B -->|存在缺失| C[自动安装依赖]
    B -->|完整| D[验证文件哈希]
    C --> D
    D --> E[选择安装位置]
    E --> F[启用/禁用状态切换]
    F --> G[记录安装状态]

对比说明

功能	Lumafly	传统手动管理	其他管理器
依赖解析	✅ 自动递归解析	❌ 手动查找	⚠️ 仅一级依赖
版本控制	✅ 支持版本锁定	❌ 无	⚠️ 有限支持
冲突检测	✅ 哈希校验机制	❌ 无	⚠️ 基础文件名检查

1.2 离线优先的资源获取

Lumafly采用双缓存机制确保网络不稳定时仍能正常使用。系统会自动缓存已下载的模组安装包和API清单，当检测到网络连接中断时，会无缝切换到离线模式继续工作。这对于校园网或网络条件较差的环境特别友好。

深入了解：缓存管理机制

Lumafly维护两种缓存：

1. 模组缓存：位于HKInstallerCache目录，存储下载的ZIP/DLL文件，校验SHA256确保完整性
2. 链接缓存：Modlinks.xml和ApiLinks.xml的本地备份，支持完全离线启动

通过"设置→高级"中的"低存储模式"可自动清理缓存，适合存储空间有限的设备。

环境准备

2.1 系统要求与兼容性

Lumafly基于Avalonia框架构建，实现了真正的跨平台支持。无论是Windows的Steam版、macOS的App Store版，还是Linux的Flatpak版Hollow Knight，都能完美适配。

⚠️ 注意事项：Linux用户需确保安装libunwind8和libssl1.1依赖包，否则可能出现启动失败。可通过以下命令安装：

sudo apt install libunwind8 libssl1.1

2.2 快速安装指南

获取Lumafly的三种方式：

1. 源码编译（适合开发者）：

git clone https://gitcode.com/gh_mirrors/lu/Lumafly
cd Lumafly
dotnet build Lumafly.sln -c Release

2. 预编译版本：从项目发布页下载对应平台的压缩包，解压后直接运行可执行文件。

3. 包管理器（Linux）：

# 暂无官方包，社区维护版本可能存在
flatpak install flathub com.github.lumafly

💡 安装后验证：首次启动时，Lumafly会自动检测游戏路径。若检测失败，可手动选择Hollow Knight安装目录下的Managed文件夹。

配置指南

3.1 基础设置详解

Lumafly的配置系统采用分层设计，分为全局设置和用户偏好：

• 全局设置：存储在HKInstallerSettings.json，包含游戏路径、缓存策略等关键信息
• 用户偏好：包括界面语言、下载镜像等个性化选项

通过"设置"界面可配置的核心选项：

• 自动清理未使用依赖：推荐设为"卸载时"，自动移除不再需要的模组
• 下载镜像选择：国内用户可启用GitHub镜像加速下载
• 语言设置：支持10种语言，包括简体中文、日语和俄语等

3.2 新手常见配置错误对照表

错误现象	可能原因	解决方案
启动时提示"无法找到游戏"	游戏路径配置错误	1. 确认选择的是Hollow Knight_Data/Managed文件夹 2. 验证游戏文件完整性
模组安装后不生效	安装路径权限不足	1. 避免将游戏安装在Program Files目录 2. 以管理员身份运行Lumafly
中文显示乱码	系统区域设置问题	1. 在设置中切换至"zh"语言 2. 重启应用使设置生效
无法更新模组	网络连接受限	1. 检查防火墙设置 2. 手动下载更新包放入HKInstallerCache

⚠️ 危险操作：不要手动编辑HKInstallerSettings.json文件，错误的JSON格式会导致配置丢失。如需修改，使用"设置→高级→编辑配置文件"功能。

进阶技巧

4.1 模组包管理

Lumafly的模组包功能允许你创建和分享模组组合，特别适合以下场景：

• 保存不同游戏风格的模组配置（如"速通包"、"剧情包"）
• 与朋友分享完整的模组设置
• 备份当前模组状态，防止误操作

创建模组包的步骤：

1. 在"模组包"标签页点击"新建"
2. 输入名称和描述
3. 选择要包含的模组版本
4. 点击"导出"生成.lumpack文件

💡 分享技巧：导出时勾选"包含版本信息"，确保接收方获得完全一致的模组版本。

4.2 故障排查工具箱

当遇到问题时，Lumafly提供多种诊断工具：

1. 日志查看器：通过"帮助→查看日志"访问，记录了所有操作和错误信息
2. 依赖关系图：在模组详情页点击"查看依赖"，可视化展示依赖链
3. 文件锁定检测：自动识别占用游戏文件的进程，解决"无法写入"错误

深入了解：高级调试技巧

高级用户可通过以下方式获取更详细的诊断信息：

1. 启用详细日志：在快捷方式后添加--verbose参数
2. 查看API响应：日志中搜索"FetchWithFallback"查看网络请求
3. 验证哈希值：对比ModItem.Sha256与本地文件计算值

常见问题的日志关键词：

• HashMismatchException：文件损坏或被篡改
• InvalidModlinksException：模组清单格式错误
• FileAccessLookup：文件锁定问题

社区贡献快速通道

5.1 翻译贡献

Lumafly采用Crowdin进行多语言管理，即使不懂代码也能参与翻译：

1. 访问项目翻译平台（社区维护）
2. 选择熟悉的语言
3. 翻译或校对字符串
4. 提交审核，无需技术背景

💡 翻译技巧：关注Resources.xx.resx文件，重点翻译游戏术语和UI元素，保持一致性。

5.2 代码贡献

对于开发者，贡献代码的流程简化为：

1. Fork项目仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交遵循Conventional Commits规范的变更
4. 创建PR并描述功能用途和测试方法

核心贡献方向：

• 支持新的模组源（如ModDB、NexusMods）
• 优化UI/UX体验
• 添加平台特定功能（如Steam Deck触控优化）

⚠️ PR要求：所有代码必须通过现有单元测试，并新增相应测试用例。测试项目位于Lumafly.Tests目录。

附录：核心模块速查表

模块	功能	关键类
安装引擎	处理模组安装/卸载	Installer.cs
依赖解析	计算依赖关系	ReverseDependencySearch.cs
版本检查	应用更新管理	AppUpdater.cs
配置系统	设置管理	Settings.cs
错误处理	用户友好提示	DisplayErrors.cs

通过了解这些核心组件，你可以更深入地理解Lumafly的工作原理，甚至定制自己的功能扩展。记住，开源项目的活力来自社区贡献，无论是报告bug还是提交代码，都是宝贵的贡献！