SMAPI无法识别MOD文件夹怎么办？

Question

SMAPI无法识别MOD文件夹怎么办？一个常见原因是游戏安装路径中包含中文字符或特殊符号，导致SMAPI加载MOD时路径解析失败。建议将游戏根目录移至纯英文路径下（如C:\StardewValley），并确保“Mods”文件夹与“StardewModdingAPI.exe”同级。同时确认“Mods”命名正确且未被隐藏，避免因大小写或系统隐藏属性导致识别异常。

Answer 1

1. 问题现象与初步排查

在使用 Stardew Modding API（SMAPI）启动《星露谷物语》时，用户常遇到“MOD未加载”或“Mods 文件夹无法识别”的提示。最直观的表现是 SMAPI 启动日志中显示：No mods found in the Mods folder，即便该目录下已放置多个合法 MOD。

此时应首先确认以下几点：

• 游戏根目录是否包含中文字符或特殊符号（如：空格、括号、#、& 等）；
• Mods 文件夹是否存在且命名准确为 Mods（注意大小写）；
• Mods 文件夹是否被操作系统标记为“隐藏”属性；
• StardewModdingAPI.exe 与 Mods 文件夹是否处于同一层级目录。

2. 路径编码与文件系统兼容性分析

SMAPI 基于 .NET Framework 构建，在处理文件路径时依赖底层操作系统的路径解析机制。当游戏安装路径含有非 ASCII 字符（如中文“我的游戏”）或特殊符号（如“C:\Games\Stardew (v1.6)”），.NET 的 DirectoryInfo 或 Path.Combine 方法可能因编码不一致导致路径拼接错误。

例如：

string modPath = Path.Combine(gameRoot, "Mods");
// 若 gameRoot = "C:\\游戏\\Stardew"
// 实际解析可能失败或返回 null

此类问题在 Windows 上虽不总是立即暴露，但在跨平台移植或调用原生库时极易引发异常。

3. 目录结构规范与层级验证

正确的 SMAPI 项目结构应如下表所示：

文件/目录	位置要求	说明
StardewValley.exe	根目录	主游戏可执行文件
StardewModdingAPI.exe	根目录	必须与 Mods 同级
Mods	根目录	名称严格区分大小写
mods/[mod_name]	子目录结构	每个 MOD 应独立成文件夹

4. 隐藏属性与文件系统元数据检查

Windows 资源管理器默认隐藏某些系统属性文件夹，若用户曾手动创建 Mods 文件夹并误设“隐藏”属性，则 SMAPI 将跳过扫描。

可通过命令行检测：

attrib "C:\StardewValley\Mods"

输出示例：

A---- C:\StardewValley\Mods

其中“A”表示存档属性，“H”表示隐藏。若出现“H”，需执行：

attrib -H "C:\StardewValley\Mods"

5. 自动化诊断流程图

为提升排查效率，可构建如下诊断逻辑：

graph TD
            A[SMAPI 启动失败] --> B{路径含中文或特殊字符?}
            B -- 是 --> C[移动至纯英文路径]
            B -- 否 --> D{Mods 文件夹存在?}
            D -- 否 --> E[创建 Mods 文件夹]
            D -- 是 --> F{命名正确且非隐藏?}
            F -- 否 --> G[重命名并取消隐藏]
            F -- 是 --> H[检查 SMAPI 日志]
            H --> I[确认 MOD 格式合规]
            I --> J[成功加载 MOD]

6. 深层调试建议与日志分析

SMAPI 在运行时生成 smapi-output.txt 日志文件，位于游戏根目录。关键排查点包括：

• Loading mods from: [path] —— 观察实际解析路径是否符合预期；
• Skip invalid mod at path —— 表明 MOD 结构不符合 manifest.json 规范；
• Access to the path is denied —— 权限或防病毒软件拦截。

建议启用开发者模式，在 PowerShell 中以管理员身份运行 SMAPI，并捕获完整异常堆栈。

7. 多环境部署注意事项

对于 IT 运维或自动化部署场景，推荐使用脚本统一管理路径规范化：

# deploy.ps1
$gameRoot = "C:\StardewValley"
if ((Get-Item $gameRoot).Name -ne "StardewValley") {
    throw "路径名不应包含中文"
}
$modFolder = Join-Path $gameRoot "Mods"
if (!(Test-Path $modFolder)) {
    New-Item -ItemType Directory -Path $modFolder
}
Set-ItemProperty -Path $modFolder -Name Attributes -Value Normal

此脚本确保路径纯净、目录存在且无隐藏属性。