本指南涵盖了在 Legion Hosting 上托管的 Project Zomboid 服务器的高级模组故障排除。如果您尚未安装模组，请先参阅基础模组安装指南。本文解决了 Legion Hosting 支持工单中最常见的模组相关问题，包括 WorldDictionary 损坏、模组格式错误、加载顺序冲突以及服务器与客户端之间的版本不匹配。

开始之前

• 登录 GPanel 并选择您的 Project Zomboid 服务器。
• 在进行任何配置或文件更改之前，请停止服务器。
• 在尝试任何修复之前，通过 SFTP 或 GPanel 备份您的世界存档文件夹（/.cache/saves/multiplayer/）。如果您不熟悉文件传输，请参阅 SFTP 指南。
• 准备好您服务器的 .ini 文件路径：/.cache/server/<servername>.ini（例如 servertest.ini）。

---

1. 模组格式错误（B42 与 B41）

模组无法加载的最常见原因是服务器 .ini 文件中 Mods= 行的格式不正确。Build 42 和 Build 41 使用不同的语法，混用会导致模组静默加载失败。

B42 格式（当前默认）

Build 42 要求在 Mods= 行中每个 Mod ID 前添加反斜杠前缀：

Mods=\ModID1;\ModID2;\ModID3;

DLMP 格式使用反斜杠分隔符将 Workshop ID 和 Mod ID 组合在一起：

Mods=2392987841\ModID1;1550458773\ModID2;2786383654\ModID3;

WorkshopItems= 行在两个版本上使用相同的分号分隔格式：

WorkshopItems=2392987841;1550458773;2786383654

B41 格式（旧版）

Build 41 使用纯分号分隔的 Mod ID，不带反斜杠：

Mods=ModID1;ModID2;ModID3

修复方法

1. 在 GPanel 文件管理器中打开 /.cache/server/<servername>.ini。
2. 找到 Mods= 行并对照上述示例检查格式。
3. 如果格式与您的版本不匹配，请更正它。使用 Legion Hosting Mod Organizer 自动生成正确格式的行。
4. 保存文件并启动服务器。

---

2. WorldDictionary 损坏

WorldDictionary 是一个文件（WorldDictionary.bin），用于将物品名称映射到内部数字 ID。当添加或删除模组时，字典可能会损坏，导致服务器启动时崩溃并出现 WorldDictionaryException。

症状

• 控制台或 debug.log 显示 WorldDictionaryException 或 WorldDictionary 错误。
• 服务器在启动期间立即崩溃，特别是在世界加载阶段。
• 崩溃在添加、删除或更新模组后开始发生。

了解风险

恢复步骤

1. 在 GPanel 中停止服务器。
2. 通过 SFTP 备份整个存档文件夹：将完整的 /.cache/saves/multiplayer/<YourWorldName>/ 目录下载到本地计算机。
3. 首先，尝试简单地撤销导致错误的模组更改。如果您刚添加了一个模组，请从 .ini 文件的 Mods= 和 WorkshopItems= 中删除它。如果您刚删除了一个模组，请将其添加回去。启动服务器查看崩溃是否已解决。
4. 如果撤销模组更改无效，请通过 SFTP 连接并导航到 /.cache/saves/multiplayer/<YourWorldName>/。
5. 删除 WorldDictionary.bin。
6. 启动服务器。Project Zomboid 将在启动时重新生成字典。
7. 加入服务器并检查世界中是否有损坏的物品、消失的载具或损坏的背包。如果世界严重受损，请从步骤 2 中创建的备份进行恢复。

---

3. Authentic Z 模组冲突

Authentic Z 是最受欢迎的 Project Zomboid 模组合集之一，但它是支持工单的常见来源，因为它包含多个相互冲突的子模组。

规则

常见错误

• 同时添加 Authentic Z - Current 和 Authentic Z - Litemode。
• 将专为单人游戏设计的 Authentic Z 子模组与多人版本一起添加。
• 没有意识到不同的 Authentic Z 子模组共享相同的 Workshop ID 但有不同的 Mod ID，因此 Workshop 下载成功但服务器加载了冲突的模组文件。

修复方法

1. 在 GPanel 文件管理器中打开 /.cache/server/<servername>.ini。
2. 在 Mods= 行中搜索所有包含 Authentic 或 AuthenticZ 的条目。
3. 只保留一个 Authentic Z 子模组（推荐：Authentic Z - Current）。从 Mods= 和 WorkshopItems= 行中删除所有其他 Authentic Z 条目。
4. 保存文件并重启服务器。

---

4. Linux 大小写敏感问题

Legion Hosting 服务器运行在 Linux 上，文件和文件夹名称区分大小写。名为 MyMod.lua 和 mymod.lua 的文件被视为两个完全不同的文件。当模组作者在 Windows（不区分大小写）上开发，而其模组包含不匹配的文件引用时，就会出现问题。

症状

• 模组在您的 Windows PC 上单人游戏中运行完美，但在服务器上失败。
• 控制台或 debug.log 显示 FileNotFoundException 或 can't find file 错误，引用模组内的 Lua 脚本或纹理。
• 错误指向模组文件夹中确实存在的文件，但大小写不同（例如，代码引用 Items.txt 但实际文件名为 items.txt）。

诊断方法

1. 检查控制台或 /.cache/Logs/ 日志文件中错误提到的确切文件路径。
2. 通过 SFTP 连接并导航到模组文件夹 /steamapps/workshop/content/108600/<WorkshopID>/。
3. 将磁盘上的文件名与错误消息中引用的文件名进行比较。查找大小写差异。

修复方法

• 如果您可以重命名文件：通过 SFTP 连接并重命名文件以匹配模组代码期望的大小写。请注意，如果模组在 Steam Workshop 上更新，此修复将被覆盖。
• 如果问题出在模组本身：在 Steam Workshop 页面上向模组作者报告此错误。说明文件引用存在大小写不匹配，并且在 Linux 服务器上会失败。许多模组作者不了解 Linux 的大小写敏感性。
• 作为临时解决方案：查看模组的 Workshop 页面评论——其他 Linux 服务器运营商可能已发布修复方案或该模组的兼容分支。

---

5. 模组加载顺序问题

Project Zomboid 按照 Mods= 行中出现的顺序加载模组。某些模组依赖于其他模组先被加载。如果依赖项在需要它的模组之后加载，则依赖模组可能会静默失败或导致错误。

症状

• 模组功能部分正常——模组中的某些物品或系统存在，但其他的缺失。
• 控制台显示引用模组 Lua 脚本的 NullPointerException 或 attempt to index a nil value 错误。
• 仅当安装特定模组组合时才出现错误，但每个模组单独运行时都正常。

修复方法

1. 查看每个模组的 Steam Workshop 页面中的"Required Mods"或"Load Order"部分。许多模组作者会指定哪些模组必须在其模组之前加载。
2. 打开 /.cache/server/<servername>.ini 并找到 Mods= 行。
3. 重新排列条目，使依赖模组出现在需要它们的模组之前。例如，如果 Mod B 依赖 Mod A，该行应为 Mods=\ModA;\ModB;（B42 格式）。
4. 框架和库模组（如 ModFramework、TsarLib 或 Shark's Mod Utils）应始终列在 Mods= 行的最前面。
5. 保存文件并重启服务器。

---

6. 添加模组后服务器崩溃

如果您的服务器之前运行正常，在添加一个或多个模组后崩溃，那么新模组很可能是原因。本节将引导您隔离问题模组。

逐步隔离

1. 在 GPanel 中停止服务器。
2. 在文件管理器中打开 /.cache/server/<servername>.ini。
3. 记下您刚添加的所有模组。从 Mods= 和 WorkshopItems= 行中删除所有这些模组。
4. 启动服务器。如果成功启动，问题出在您删除的某个模组中。
5. 逐个添加模组，每次添加后重启服务器。当崩溃再次出现时，您最后添加的模组就是原因。
6. 确定后，检查该模组的 Workshop 页面：
   • 关于 B42 兼容性的说明——许多 B41 模组尚未针对 B42 更新。
   • 与您正在运行的其他模组的已知冲突。
   • 您可能未安装的必需依赖模组。

查看崩溃日志

在执行隔离过程之前，检查崩溃日志——它通常直接指向问题模组：

1. 在 GPanel 中，打开Console标签页并滚动到输出末尾。
2. 查找 STACK TRACE、Exception 或 ERROR 行。
3. 堆栈跟踪正上方的行通常引用模组文件名或 Mod ID——这会告诉您哪个模组触发了崩溃。
4. 如需更多详细信息，通过 SFTP 打开 /.cache/Logs/ 中的完整日志文件，查看最新的 DebugLog-server.txt 或 debug.log 文件。

---

7. 模组版本不匹配（服务器与客户端）

Project Zomboid 要求服务器和所有连接的客户端拥有每个模组的相同版本。如果模组在 Steam Workshop 上更新，服务器下载了新版本但玩家仍然缓存了旧版本（或反之），将会出现连接失败或崩溃。

症状

• 玩家尝试连接时收到"Mod mismatch"或"Version mismatch"错误。
• 某些玩家可以连接但其他人不能——无法连接的玩家本地缓存了不同的模组版本。
• 服务器之前运行正常，然后一个模组在 Steam Workshop 上更新后，突然有些玩家无法加入。
• 玩家看到最近更新的模组中缺少纹理、物品或界面元素损坏。

服务器管理员的修复方法

1. 在 GPanel 中停止服务器。
2. 重新启动服务器。启动时，服务器会重新下载所有 Workshop 模组的最新版本。这确保服务器运行的是最新版本。
3. 如果服务器仍然缓存了旧版本，通过 SFTP 连接并删除特定模组的 Workshop 缓存文件夹 /steamapps/workshop/content/108600/<WorkshopID>/。重启服务器以强制重新下载。

玩家的修复方法

因模组版本不匹配而无法连接的玩家应：

1. 打开 Steam 并导航到 Library → Project Zomboid。
2. 右键点击 Project Zomboid，选择 Properties → Local Files → Verify Integrity of Game Files。
3. 同时导航到本地计算机上 Project Zomboid 的 Steam Workshop 文件夹，删除缓存的模组文件以强制重新下载。
4. 启动游戏并重新连接到服务器。

---

8. 清除 Steam Workshop 缓存

如果多个模组问题持续存在且您怀疑 Workshop 下载缓存已损坏，可以强制完全重新下载所有 Workshop 模组。

1. 在 GPanel 中停止服务器。
2. 通过 SFTP 连接并导航到 /steamapps/workshop/。
3. 删除整个 workshop/ 文件夹（或其内容）。
4. 启动服务器。Steam 将从头开始重新下载所有 Workshop 项目。
5. 观察 GPanel 控制台确认所有模组在服务器开始世界加载之前下载完成。

---

快速诊断参考

---

仍然有模组问题？