【深度解析】Linux平台下Scarab识别GoG版Hollow Knight的技术瓶颈与解决方案

2026-02-04 04:30:10作者：龚格成

问题背景：Linux玩家的痛点

当Linux用户尝试使用Scarab安装Hollow Knight模组时，部分GoG版本玩家会遇到程序无法自动定位游戏可执行文件的问题。这一现象源于Scarab在跨平台路径检测逻辑中对GoG版本的支持不足，导致玩家需要手动指定游戏路径才能正常使用模组管理器。本文将从代码层面深入分析问题根源，并提供完整的解决方案。

技术分析：路径检测机制的现状

Scarab的路径检测系统主要通过Settings.cs和PathUtil.cs两个核心文件实现，其工作流程如下：

flowchart TD
    A[启动路径检测] --> B[检查静态路径列表]
    B -->|找到有效路径| C[返回结果]
    B -->|未找到| D[检查用户目录路径]
    D -->|找到有效路径| C
    D -->|未找到| E[尝试注册表检测]
    E -->|Windows系统| F[检查Steam/GOG注册表项]
    E -->|非Windows系统| G[返回检测失败]
    G --> H[提示用户手动选择路径]

关键代码解析：路径定义与检测逻辑

在Settings.cs中，系统定义了多组路径模板：

// Settings.cs 静态路径定义
private static readonly ImmutableList<string> STATIC_PATHS = new List<string>
{
    "Program Files/Steam/steamapps/common/Hollow Knight",
    "Program Files (x86)/Steam/steamapps/common/Hollow Knight",
    "Program Files/GOG Galaxy/Games/Hollow Knight",  // Windows平台GoG路径
    "Program Files (x86)/GOG Galaxy/Games/Hollow Knight",
    // 其他路径...
}.SelectMany(path => DriveInfo.GetDrives().Select(d => Path.Combine(d.Name, path))).ToImmutableList();

// Linux特定路径
private static readonly ImmutableList<string> USER_SUFFIX_PATHS = new List<string>
{
    ".local/share/Steam/steamapps/common/Hollow Knight",  // Steam版本
    ".steam/steam/steamapps/common/Hollow Knight",
    ".var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/Hollow Knight",
    ".steam/root/steamapps/common/Hollow Knight",
    // 缺少Linux GoG版本路径定义
}.ToImmutableList();

检测逻辑通过TryAutoDetect方法实现：

// Settings.cs 路径检测流程
internal static bool TryAutoDetect([MaybeNullWhen(false)] out ValidPath path)
{
    // 检查静态路径
    path = STATIC_PATHS.Select(PathUtil.ValidateWithSuffix)
                       .OfType<ValidPath>()
                       .FirstOrDefault();

    if (path is not null) return true;

    // 检查用户目录路径
    string home = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
    path = USER_SUFFIX_PATHS
        .Select(suffix => Path.Combine(home, suffix))
        .Select(PathUtil.ValidateWithSuffix)
        .OfType<ValidPath>()
        .FirstOrDefault();
    
    return path is not null || TryDetectFromRegistry(out path);  // 注册表检测仅Windows有效
}

验证逻辑：游戏目录结构检查

PathUtil.ValidateWithSuffix方法负责验证路径是否包含有效的游戏目录结构：

// PathUtil.cs 路径验证逻辑
public static PathResult ValidateWithSuffix(string? root)
{
    if (!Directory.Exists(root))
        return new RootNotFoundError();
            
    string? suffix = SUFFIXES.FirstOrDefault(s =>
    {
        string p = Path.Combine(root, s);
        return Directory.Exists(p);
    });

    if (suffix is null)
        return new SuffixNotFoundError(root, SUFFIXES.Select(s => Path.Combine(root, s)).ToArray());

    if (File.Exists(Path.Combine(root, suffix, "Assembly-CSharp.dll")))
        return new ValidPath(root, suffix);

    return new AssemblyNotFoundError(...);
}

问题定位：Linux平台GoG版本的支持缺口

通过代码分析，我们可以确定问题源于以下几个关键点：

1. 路径模板缺失

在USER_SUFFIX_PATHS列表中，仅包含了Steam版本的Linux路径，完全缺少对GoG版本的支持。GoG在Linux平台通常使用不同的安装路径结构，如~/GOG Games/Hollow Knight/或~/.local/share/GOG.com/Heroes of Might and Magic III/等变体。

2. 跨平台检测逻辑差异

注册表检测机制TryDetectFromRegistry明确限定为Windows系统：

private static bool TryDetectFromRegistry([MaybeNullWhen(false)] out ValidPath path)
{
    path = null;
    if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
        return false;  // Linux系统直接跳过注册表检测
    // ...
}

而GoG for Linux并未使用Windows注册表类似的集中式安装信息存储机制，导致Scarab无法通过类似方式获取安装路径。

3. 目录结构验证限制

GoG版Hollow Knight在Linux平台可能使用不同的目录结构后缀，而当前SUFFIXES定义可能无法覆盖所有情况：

internal static readonly string[] SUFFIXES =
{
    "Hollow Knight_Data/Managed",  // GoG Windows
    "hollow_knight_Data/Managed",  // Steam Windows
    "Contents/Resources/Data/Managed"  // MacOS
};

解决方案：完善Linux平台GoG支持

方案一：扩展路径模板（推荐）

修改Settings.cs中的USER_SUFFIX_PATHS，添加GoG Linux常见路径：

// Settings.cs 路径模板修复
private static readonly ImmutableList<string> USER_SUFFIX_PATHS = new List<string>
{
    ".local/share/Steam/steamapps/common/Hollow Knight",
    ".steam/steam/steamapps/common/Hollow Knight",
    ".var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/Hollow Knight",
    ".steam/root/steamapps/common/Hollow Knight",
+   "GOG Games/Hollow Knight",  // GoG默认安装路径
+   ".local/share/GOG.com/Heroes of Might and Magic III",  // GOG Galaxy路径变体
+   ".wine/drive_c/GOG Games/Hollow Knight",  // Wine兼容路径
    "Library/Application Support/Steam/steamapps/common/Hollow Knight/hollow_knight.app"
}
.ToImmutableList();

方案二：实现Linux特定的GoG路径检测

通过解析GoG的本地数据库文件扩展检测能力：

// Settings.cs 添加Linux GoG检测
private static bool TryDetectLinuxGog([MaybeNullWhen(false)] out ValidPath path)
{
    path = null;
    if (!RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        return false;
        
    var gogDbPaths = new[] {
        Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), 
                    ".local", "share", "GOG.com", "Galaxy", "config", "installed_games.json"),
        Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), 
                    "GOG Games", "manifest.json")
    };
    
    foreach (var dbPath in gogDbPaths)
    {
        if (File.Exists(dbPath))
        {
            // 解析GOG数据库文件提取安装路径
            var json = JsonDocument.Parse(File.ReadAllText(dbPath));
            // 实现具体的JSON解析逻辑...
            if (TryParseGogDb(json, out var gamePath))
            {
                path = PathUtil.ValidateWithSuffix(gamePath);
                return path != null;
            }
        }
    }
    return false;
}

方案三：增强路径验证的灵活性

扩展SUFFIXES数组，支持更多可能的目录结构：

// PathUtil.cs 扩展目录验证后缀
internal static readonly string[] SUFFIXES =
{
    "Hollow Knight_Data/Managed",
    "hollow_knight_Data/Managed",
    "Contents/Resources/Data/Managed",
+   "Data/Managed",  // 通用Linux后缀
+   "HollowKnight_Data/Managed"  // 可能的大小写变体
};

实施指南：手动配置与验证步骤

当自动检测失败时，用户可通过以下步骤手动配置路径：

定位GoG版安装路径
通常位于以下位置之一：
- ~/GOG Games/Hollow Knight/
- ~/.local/share/GOG.com/Hollow Knight/
- ~/Games/hollow-knight/（Flatpak版本）

验证目录结构
确保所选目录包含有效的游戏数据结构：

# 典型的GoG Linux目录结构
Hollow Knight/
├── Hollow Knight.desktop
├── gameinfo
├── Hollow Knight_Data/
│   ├── Managed/
│   │   ├── Assembly-CSharp.dll  # 关键文件
│   │   └── UnityEngine.dll
│   └── Resources/
└── hollow_knight.x86_64  # Linux可执行文件

手动设置路径
在Scarab中选择"手动指定路径"，导航至上述目录并确认。系统会自动验证Managed文件夹是否存在：

sequenceDiagram
    participant 用户
    participant Scarab
    participant 文件系统
    
    用户->>Scarab: 启动程序
    Scarab->>文件系统: 执行自动路径检测
    文件系统-->>Scarab: 返回检测失败
    Scarab->>用户: 显示路径选择对话框
    用户->>Scarab: 选择GoG安装目录
    Scarab->>文件系统: 验证路径结构
    文件系统-->>Scarab: 返回验证结果
    Scarab->>用户: 完成配置并加载模组列表

兼容性测试矩阵

为确保解决方案的全面性，建议在不同环境下进行测试：

测试场景	预期结果	实际结果	状态
Steam版Linux原生安装	自动检测成功	成功	✅
GoG版Linux原生安装	自动检测成功	失败（需修复）	❌
GoG版Wine安装	手动选择成功	成功	✅
Flatpak版Steam	自动检测成功	成功	✅
Snap版Steam	自动检测成功	成功	✅
自定义位置安装	手动选择成功	成功	✅

长期解决方案：社区协作与贡献指南

Scarab作为开源项目，欢迎社区贡献者参与完善跨平台支持：

提交issue
在项目仓库https://gitcode.com/gh_mirrors/sc/Scarab创建详细issue，包含：
- Linux发行版及版本
- GoG客户端版本
- 游戏安装路径
- 目录结构截图

代码贡献流程

# 1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/sc/Scarab.git

# 2. 创建功能分支
git checkout -b feature/linux-gog-detection

# 3. 实现修复
# 修改Settings.cs和PathUtil.cs

# 4. 提交测试
cd Scarab.Tests
dotnet test

# 5. 提交PR
git commit -m "Add Linux GoG path detection"
git push origin feature/linux-gog-detection

测试用例补充
为ModSourceTest.cs添加Linux GoG路径检测的单元测试：

[Test]
public void TestLinuxGoGPathDetection()
{
    // 模拟GoG安装路径
    var tempDir = new TemporaryDirectory();
    var gameDir = Path.Combine(tempDir.Path, "GOG Games", "Hollow Knight");
    var managedDir = Path.Combine(gameDir, "Hollow Knight_Data", "Managed");
    Directory.CreateDirectory(managedDir);
    
    // 创建测试用Assembly-CSharp.dll
    File.Create(Path.Combine(managedDir, "Assembly-CSharp.dll")).Dispose();
    
    // 执行检测
    Settings.TryAutoDetect(out var path);
    
    // 验证结果
    Assert.IsNotNull(path);
    Assert.AreEqual(gameDir, path.Root);
}