饥荒Mod全攻略：从安装配置到开发排查一次讲透-代码聚汇网

在饥荒的各个玩家群里，几乎每天都有人问同一类问题：为什么我订阅了一百多个Mod，游戏反而进不去？为什么同一个Mod在朋友那里好好的，在我这儿一开就红字？为什么有的Mod必须装服务器端，有的装客户端就行？还有不少人想自己动手写个饥荒Mod，但对着网上那些零散的教程，连modinfo.lua和modmain.lua是干什么的都搞不明白。

这篇文章我打算一次把这些事讲透。内容分成两大块：一是玩家视角，怎么把Mod装对、装稳、出问题怎么排查；二是作者视角，从零手写一个能用的饥荒Mod，把加载机制、常用API、测试方法都过一遍。无论你是只想好好用Mod的玩家，还是想动手改游戏的新手作者，都能从里面找到能直接抄作业的东西。

1. 饥荒Mod到底能改变什么？先分清“装修”和“拆承重墙”

很多人对Mod的理解是“往游戏里塞东西”，这个说法对，但太笼统。想用好Mod，甚至想写Mod，第一步得知道饥荒这个游戏的逻辑层到底是怎么组织的。

1.1 Mod是游戏留给玩家的改装接口

饥荒的核心逻辑——合成、季节、饥饿值、San值、战斗、世界生成——这些绝大部分是用Lua脚本写出来的，而不是编译死在引擎里的。这意味着游戏本身就留了一个很深的改装接口：玩家写的Lua脚本可以在游戏启动时被加载进去，把原本的数值、逻辑、物品、生物，甚至整个玩法都替换掉。

举一个最直观的例子。游戏里“石篝火的燃烧时间”是一个数值，存放在TUNING表里。一个Mod只需要几行代码，就能把这个数值改大改小，或者把它改成无限。这种改动不需要碰游戏本体，只是在你启动游戏的时候，脚本被额外执行了一遍，把原来的数值覆盖掉了。

所以Mod能做的事，远不止“加几个物品”。它能改UI布局，能在地图上画格子（几何布局Mod就是这么干的），能改变怪物AI，能重新定义四季长度，能加一整套新角色和新科技树。大型Mod比如神话书说、棱镜，本质上是往饥荒里塞了一个全新的游戏内容包，靠的依然是这套Lua接口。

1.2 三类常见的饥荒Mod

按玩家实际使用场景，我习惯把Mod分成三类。这个分类对后面理解“为什么会崩”“该装哪一端”特别重要。

第一类是显示辅助类。典型代表是几何布局（Geometric Placement）、显示食物属性（Smart Minisign）、小地图（Minimap HUD）。这类Mod只改变你屏幕上的信息呈现方式，不改变游戏世界的数据，存档里也不会写入任何Mod相关的东西。它们通常做成“客户端Mod”，只对你一个人生效，别人装不装都无所谓。

第二类是功能扩展类。典型代表是快速拾取、自动堆叠、智能锅、灭火器范围扩大这类。它们会改变游戏机制本身，比如把捡东西的判定范围变大，或者让锅自动停止烹饪。这类Mod有的只需要客户端就能实现，有的必须服务器端执行，具体看它改的是“你的操作体验”还是“世界逻辑”。

第三类是内容重构类。新增角色、新增生物、新增BOSS、修改整个季节机制，这类Mod是写进存档里的。你玩一个带新物品的Mod，存档里就会记录这个物品的实例数据。一旦关闭Mod再进旧档，游戏读不到对应的Prefab，轻则物品消失，重则直接崩溃。

1.3 边界在哪：Mod改不了什么

说了这么多“能改”，也得说说“不能改”。理解这个边界，能帮你避免很多不切实际的期待，也能解释为什么有些Mod做不出来。

饥荒的游戏引擎底层（图形渲染、物理碰撞、网络同步框架）是C++写的，编译在可执行文件里。Lua脚本能访问的是引擎开放出来的一层API，够用，但不是万能的。比如你想给游戏加一个全新的渲染管线，或者修改水面反射特效，这类需求Lua基本做不了，只能靠Shader Mod这种走引擎着色器接口的Mod，而且限制也很多。

另外一个限制是网络同步。联机版里，客户端看到的画面和服务器计算的逻辑是两套东西。一个Mod如果想在服务器上生成一个全服玩家都能见到的物品，它必须作为服务器Mod运行，服务器端生成实体后，再通过网络把状态同步给所有客户端。这也就是为什么有的Mod在单人模式好好的，一进联机房间就失灵。

提示：判断一个Mod能不能做，先问自己三个问题——它改的是显示信息，还是世界数据？它需不需要所有玩家都看到同样的结果？它的运行范围在客户端还是服务器？想清楚这三点，就明白一个大半了。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 从加载机制说起：为什么Mod会冲突、会崩溃

装Mod久了你会发现一个规律：大部分崩溃不是Mod作者写得太烂，而是Mod之间互相踩了，或者Mod跟当前游戏版本不匹配。想搞明白这些，得先知道饥荒是怎么加载一个Mod的。

2.1 一个Mod文件夹里都有什么

打开任意一个饥荒Mod的文件夹，里面通常有这么几个东西：

modinfo.lua：给游戏看的“Mod说明书”，包括名字、作者、版本、兼容性标记。
modmain.lua：Mod的主逻辑文件，游戏启动时会执行这里面的代码。
prefab文件夹：如果你这个Mod加了新物品或新生物，通常会在这里放对应的Prefab定义文件。
images、anim、sound等文件夹：资源文件，放图标、贴图、动画、音效。
modicon.tex / modicon.xml：Mod在游戏列表里显示的图标。

对玩家来说，看到一个Mod文件夹，至少要能确认modinfo.lua是不是在这个根目录下。经常有人手动下载Mod后，把整个文件夹又套了一层，导致游戏找不到modinfo，最后这个Mod在列表里根本不显示。

2.2 modinfo.lua：模组的身份证

modinfo.lua是每个Mod必须有的文件。它不是一个“配置说明”，而是游戏启动时第一个被读取并执行的Lua脚本。它的返回值是一个大表，里面所有字段直接决定游戏怎么对待这个Mod。

下面是一个典型的modinfo.lua，我给每一行都加了注释：

lua复制name = "Warm Amulet - 温暖护符"        -- Mod在列表里显示的名字
description = "一个可以制作的保暖护符，冬天不再怕冷"  -- 鼠标悬停时的说明
author = "YourName"                  -- 作者名
version = "1.0.0"                    -- 版本号，更新时一定要改
api_version = 10                     -- 依赖的游戏API版本

-- 兼容性标记：这两项在联机版特别重要
dont_starve_compatible = false       -- 是否兼容单机版
dst_compatible = true                -- 是否兼容联机版（DST）
client_only_mod = false              -- 是否仅客户端Mod
all_clients_require_mod = true       -- 是否所有客户端都必须装同一个Mod

-- 图标
icon_atlas = "modicon.xml"
icon = "modicon.tex"

这里最容易踩的坑就是client_only_mod和all_clients_require_mod这两个字段。很多新手作者不清楚它们的作用，随便写了个false，结果做出来的Mod在联机房间里要么不生效，要么别人进来就掉线。具体机制我在第5章详细讲。

2.3 modmain.lua：游戏启动时执行的入口

modmain.lua是Mod的心脏。游戏启动时，如果检测到Mod被启用，会加载这个文件并执行里面的代码。在这个文件里，你可以访问全局环境GLOBAL，然后调用游戏开放的各种API来修改游戏。

新手最容易误解的一点是：modmain.lua不是“每帧运行”的，它只是在游戏启动阶段跑一遍。你在这个文件里注册事件监听器、添加配方、注入Prefab定义，但注册完之后，脚本的顶层代码就结束了。实际运行时的逻辑，是由你注册的那些回调函数来承担的。

举个例子，如果你想给所有角色增加夜晚视野，你不会在modmain.lua里写一个循环去每帧改数值，而是应该监听某个事件，或者在某个Prefab创建时（AddPrefabPostInit）给它的组件添加一个定时器。这就是“面向事件的Mod编程”和“面向过程的修改脚本”的区别。

2.4 为什么Mod之间会打架

饥荒的Mod不是沙盒隔离的。两个Mod都在改同一个Prefab，游戏加载时两个修改都会执行，后加载的可能会覆盖先加载的某些设置。如果两个Mod作者都用了不同的思路去修改同一个组件，轻则功能异常，重则报错崩溃。

这就是为什么你看到创意工坊里有些Mod描述里写着“与XXMod不兼容”。其实“不兼容”很多时候不是故意的，而是两个Mod都动了同一块蛋糕，而且没人协调切法。

解决冲突有两个层面的思路。玩家层面，学会用最小化原则去组合Mod，同类功能只留一个；作者层面，遵循“追加修改而不覆盖原文件”的原则，尽量用AddPrefabPostInit而不是直接替Prefab重新定义。这个原则我后面会详细展开。

3. 手写第一个饥荒Mod：做一个“温暖护符”

理论讲再多，不如上手写一个。我挑一个非常适合新手的项目：做一个叫“温暖护符”的装备，戴上之后能抵抗冬季寒冷。选它有四个原因：第一，它不需要自己做贴图和动画，可以复用游戏里已有的装备动画；第二，逻辑简单，只涉及Prefab定义、配方注册、组件设置；第三，它真实可玩，不是那种写完就没用的玩具代码；第四，它涉及了写Mod最核心的一条链路——写文件、注册资源、生成Prefab、测试修错。

3.1 先想清楚这个Mod要干什么

在动手写代码之前，先把这个东西的功能定义清楚。我的“温暖护符”需求如下：

可在科学机器处制作，需要2个金块和1个齿轮。
装备在项链槽位，提供强保暖效果。
有耐久度，用一段时间会坏。
外观先用游戏自带的“蓝色护符”动画代替。

这个需求已经足够清晰了。它没有复杂的跨Prefab联动，没有客户端服务器区分，没有存档结构变更，对新手非常友好。

3.2 搭建目录和modinfo.lua

在游戏本体Mod目录（或者你自己建的开发目录）里，新建一个文件夹，名字叫WarmAmulet。注意文件夹名最好用英文，不要有空格，因为游戏在加载文件时对中文和空格的处理偶尔会出幺蛾子。

然后创建modinfo.lua：

lua复制name = "Warm Amulet - 温暖护符"
description = "戴上它，冬天不再寒冷。消耗金块和齿轮制作。"
author = "YourName"
version = "1.0.0"
api_version = 10
dont_starve_compatible = false
dst_compatible = true
client_only_mod = false
all_clients_require_mod = true

icon_atlas = "modicon.xml"
icon = "modicon.tex"

关于icon_atlas和icon，如果你暂时没有做图标，可以把这两行注释掉。游戏在Mod列表里会用默认图标替代，不影响功能。

3.3 modmain.lua里注册资源和配方

创建modmain.lua，这是整个Mod的入口：

lua复制-- 引入全局表
local GLOBAL = GLOBAL

-- 声明这个Mod需要加载的Prefab文件
PrefabFiles = {
    "warm_amulet",
}

-- 声明这个Mod需要加载的图片资源
-- 这里复用了游戏自带的icons，所以不需要自己准备贴图
Assets = {
    Asset("ATLAS", "images/inventoryimages/warm_amulet.xml"),
    Asset("IMAGE", "images/inventoryimages/warm_amulet.tex"),
}

-- 向游戏注册合成配方
-- 科学机器一级解锁，工具栏标签下
local recipe = GLOBAL.AddRecipe2("warm_amulet", {
    GLOBAL.Ingredient("goldnugget", 2),
    GLOBAL.Ingredient("gears", 1),
}, GLOBAL.RECIPETABS.TOOLS, GLOBAL.TECH.SCIENCE_ONE)

-- 如果你的Mod需要给已有的Prefab追加逻辑，可以用AddPrefabPostInit
-- 比如你想让所有角色装备护符时额外增加San值回复，可以在这里写

看到Asset("ATLAS", "images/inventoryimages/warm_amulet.xml")这段，新手可能会问：我不是说不用自己做贴图吗？这里有个细节：配方的图标需要一张贴图。如果你不想自己做，一个土办法是把游戏原版“蓝护符”的图标文件复制一份，重命名为warm_amulet.xml和warm_amulet.tex，放进images/inventoryimages目录。虽然显示的是蓝护符的图标，但能正常显示在合成栏里。

3.4 护符本体：prefab文件

在modmain.lua里我们声明了PrefabFiles = { "warm_amulet" }，这意味着游戏会去找一个叫warm_amulet.lua的Prefab定义文件。现在创建prefabs/warm_amulet.lua：

lua复制local GLOBAL = GLOBAL

local function fn()
    local inst = GLOBAL.Prefab("none")

    -- 基本实体属性
    inst.entity:AddTransform()
    inst.entity:AddAnimState()
    inst.entity:AddNetwork()

    -- 设置动画：复用了游戏自带的blueamulet外观
    inst.AnimState:SetBank("amulet")
    inst.AnimState:SetBuild("blueamulet")
    inst.AnimState:PlayAnimation("anim")

    -- 可拾取物品
    inst:AddComponent("inventoryitem")
    inst.components.inventoryitem.atlasname = "images/inventoryimages/warm_amulet.xml"

    -- 可装备
    inst:AddComponent("equippable")
    inst.components.equippable.equipslot = GLOBAL.EQUIPSLOTS.NECK

    -- 保暖组件：这是护符的核心功能
    inst:AddComponent("insulator")
    inst.components.insulator:SetInsulation(GLOBAL.TUNING.INSULATION_LARGE)

    -- 耐久度：使用600秒后损坏
    inst:AddComponent("finiteuses")
    inst.components.finiteuses:SetMaxUses(600)
    inst.components.finiteuses:SetUses(600)
    inst.components.finiteuses:SetOnFinished(inst.Remove)

    -- 检查文本
    inst:AddComponent("inspectable")
    inst.components.inspectable.nameoverride = "WARM_AMULET"

    -- 装备/卸下时播放音效和特效，这里可以留空或做简单处理
    return inst
end

return GLOBAL.Prefab("warm_amulet", fn)

这个文件里有几个关键点。首先是inst.entity:AddNetwork()，这行在联机版里是必须的，没有它实体无法在网络间同步。其次是SetBank和SetBuild，这两个决定了实体的动画外观。我用的bank = "amulet"、build = "blueamulet"，就是让护符长得和游戏里蓝色护符一个样。

还有一个细节是组件之间的协作关系。equippable负责“能不能装备到项链槽”，insulator负责“装备后保暖多少”，finiteuses负责“用久了会不会坏”。这三个组件互不依赖，但组合起来就是一个完整的游戏物品。如果你漏了insulator，护符戴上后不会有任何保暖效果；如果漏了equippable，物品根本戴不上去。这种“组件拼装”的思维是饥荒Mod开发的核心。

3.5 本地测试：控制台与日志

写完代码后，把Mod文件夹放到游戏Mod目录下，在游戏开始界面启用Mod，然后开一个新档测试。

进入游戏后，按波浪号~打开控制台，输入：

code复制c_give("warm_amulet", 1)

回车后，你会直接获得一个温暖护符。如果物品出现在背包里，说明Prefab加载成功；如果没有任何反应，说明报错了，需要看日志。

日志文件在哪里？联机版在文档\Klei\DoNotStarveTogether\client_log.txt，单机版在文档\Klei\DoNotStarve\目录下。打开日志，拉到最底部，你会看到类似这样的报错：

code复制scripts/screens/playerhud.lua:123: attempt to index a nil value

报错信息会告诉你具体是哪个文件哪一行出了问题。我写Mod的时候几乎每改几行代码就要去翻一次日志，这不是坏习惯，反而是最可靠的开发方式。不要靠“看起来好像没问题”来判断，要看日志有没有新报错。

3.6 新手最容易犯的几个错

写第一个Mod，有几个坑我几乎看人踩过无数次。

第一个坑是忘掉AddNetwork()，导致联机模式下生成的物品别人看不到，或者服务器直接崩溃。这个错误在单机测试时不会暴露，因为单机没有网络同步过程。所以写完Mod，最好在联机房间（哪怕只有自己一个人）再测一遍。

第二个坑是不小心把图片资源文件写错路径。很多人自己画了图标，放在images文件夹里，但是modmain.lua里的Asset路径写得不对，比如images/inventoryimages/xxx.tex写成了images/xxx.tex。游戏加载不到纹理，会直接报错或者显示紫色的“问号”图标。解决办法是用游戏原版文件做对照，确认路径层级。

第三个坑是配方注册时用了过时的API。饥荒的食欲系统改版过几次，老教程里常出现的AddRecipe在新版本里推荐用AddRecipe2。如果你照着某篇2018年的帖子抄代码，很可能在新版本里报错。判断方法是：如果游戏提示“AddRecipe is deprecated”，说明API已经淘汰，去查官方wiki的最新写法。

第四个坑是忘记改modinfo.lua里的version。开发过程中你反复修改，但版本号一直停在1.0.0，一旦发布到创意工坊，玩家都不知道你更新了，容易产生“这个Mod不更新了”的误解。

4. 创意工坊下载与手动安装：别再放错地方了

对只玩Mod不写Mod的人来说，最大的痛点其实是“装不对地方”。这一步出错，后续的所有排查都白费。

4.1 Steam创意工坊自动订阅

大部分玩家用的是Steam创意工坊。你在创意工坊里点“订阅”之后，Steam客户端会自动把Mod下载到固定目录。联机版（Don't Starve Together）的Mod目录是：

code复制Steam\steamapps\workshop\content\322330\

单机版（Don't Starve）对应的是：

code复制Steam\steamapps\workshop\content\219740\

注意，这个目录下每个子文件夹是一串数字ID，不是Mod的原名。游戏启动时，会读取这些文件夹里的modinfo.lua，然后按你在游戏内“模组”菜单里的勾选状态来决定加载哪些。

有一个常见问题：订阅了Mod，游戏里却看不到。先别急着怀疑Mod被删了，去这个订阅目录看看，如果里面是空的，说明Steam还没下载完，或者下载出错了。解决办法是取消订阅再重新订阅，或者检查Steam的下载队列。

4.2 手动安装的正确姿势

如果你从国内Mod社区、B站专栏或网盘下载了Mod压缩包，手动安装的流程如下：

解压压缩包，确认里面第一层就是modinfo.lua。
把整个文件夹复制到游戏Mod目录。联机版的Mod目录是Steam\steamapps\common\Don't Starve Together\mods\，单机版则对应各自安装目录的mods文件夹。
文件夹名可以用中文，但强烈建议改成英文，避免某些系统下出现编码问题。
重启游戏，在“模组”菜单里勾选启用。

这里最容易犯的错是“套娃”。压缩包解压后，常见结构是my_mod_v1.0/modinfo.lua和my_mod_v1.0/scripts/...，这是正确的，直接把my_mod_v1.0整个文件夹复制进mods目录就行。但有的压缩包解压出来是downloads/my_mod_v1.0/modinfo.lua，或者my_mod_v1.0/my_mod_v1.0/modinfo.lua，这就多套了一层。游戏读不到modinfo.lua，Mod不会出现在列表里。

4.3 游戏内如何激活和排序

进入游戏主界面，选“Mods”按钮，你能看到所有已安装的Mod列表。点一下是启用，再点一下是关闭。列表下方的“配置”按钮可以调整Mod参数，但只有作者在modinfo里写了配置项才有内容。

排序问题值得一说。饥荒的Mod加载顺序是从上到下，后加载的会覆盖先加载的某些修改。所以两个功能相似的Mod，你应该把功能更全的那个放在下面，让它后加载。如果你还装了“API类”Mod（比如很多大型Mod会要求先装某个前置库），那么前置必须尽量排在上面，否则依赖它加载的其他Mod会找不到API直接报错。这个排序逻辑和电脑软件装驱动的顺序是一个道理。

提示：如果一个Mod在创意工坊页面明确写了“需要XX前置Mod”，一定要先装前置。前置没装而直接加载主Mod，九成会红字。

4.4 适合不同需求的Mod推荐

考虑到很多读者可能刚接触Mod，我推荐几类常用且口碑稳定的Mod，按需求区分。

如果你只想要更舒适的原版体验：几何布局（Geometric Placement）帮你摆放建筑时对齐格子，显示食物属性（Show Me / Smart Minisign）让你看清食物能回多少属性，快速拾取类Mod可以一键捡起周围所有掉落物。这三个都是经典中的经典，对游戏平衡影响很小。

如果你想玩大型内容Mod：神话书说、棱镜、永不妥协、旅者背包都属于体量很大的Mod。注意这类Mod通常有多个版本匹配不同的游戏版本，下载前一定要看描述里写的兼容范围。而且它们会改变很多基础机制，建议单独开新档玩，不要跟原版存档混在一起。

如果你喜欢挑战高难度：可以在创意工坊搜“Boss”“Hard”这类关键词，通常会找到增加BOSS血量、增加敌对生物种类、改变四季机制的Mod。这类Mod最考验兼容性，装多了很容易出问题，建议只保留一个，配合几个显示辅助类Mod使用。

5. 联机版特有的坑：客户端Mod和服务端Mod不是一回事

单机版里，Mod只有一套逻辑，加载到本地就完事了。联机版则复杂得多——一台主机（服务器）和一群客户端（玩家）各自运行着一套游戏实例。你的Mod装在谁那边，决定了它能不能生效，以及它对别人有没有影响。

5.1 两类Mod的生效范围

联机版Mod分两类：服务端模组（Server Mod）和客户端模组（Client Mod）。

服务端Mod在主机的世界里运行。新增物品、修改BOSS属性、改变世界生成规则，这些必须由服务器来算，然后把结果同步给所有客户端。你建房间的时候，在“模组”设置里勾选启用的，就是服务端Mod。其他玩家进你这个房间，不需要装同样的Mod，服务器会把Mod产生的内容推送给他们。

客户端Mod只在你自己本地运行。几何布局、显示食物属性、小地图、技能快捷键提示，这些改的只是你自己的显示和操作体验，不改变世界数据。你在地图上画格子，别人看不到；你看到食物属性，别人看不到。所以客户端Mod只需要你一个人装，其他人装不装都无所谓。

5.2 all_clients_require_mod 到底管什么

服务端Mod又细分为两种情况。如果你这个Mod只在服务器上改变了数值，客户端不需要做任何额外处理，那么all_clients_require_mod = false就够了，其他玩家进房会自动收到服务器计算好的结果。

但是，如果你的Mod给游戏加了新的Prefab（比如新增了一个物品、一个生物），而客户端本地没有这个Prefab的定义，那么服务器把这个新物体验证给客户端时，客户端会因为“找不到Prefab”而报错，轻则显示异常，重则直接掉线。

这种情况，modinfo.lua里的all_clients_require_mod就要设成true，意思是“所有客户端都必须装这个Mod才能进房”。游戏会在客户端连接时检查本地是否装了匹配的Mod，没装就拒绝进房。

这也是为什么很多大型内容Mod下载页都写着“所有人需要安装”——因为它们新增了大量Prefab，每个玩家本地必须有一份同样的定义，才能正确显示和交互。

5.3 主机迁移后Mod为什么会失效

联机房间有个特殊机制叫“主机迁移”。房主把房间转让给另一个玩家后，新主机的本地Mod配置会成为房主的生效配置。如果你在旧主机上装了一堆服务端Mod，而新主机没装，或者装的是不同版本的同一个Mod，迁移之后世界可能变得奇奇怪怪——新物品消失、Mod功能不再生效、甚至读档时直接崩溃。

所以联机玩Mod之前，最好先确认房间里谁有固定的Mod配置，谁适合当长期主机。混沌房间里频繁迁移主机，配上大型Mod，几乎是定时炸弹。

5.4 “Mod不生效”的快速诊断

每次有人跑来问“为什么我的Mod不生效”，我一般先问三个问题：

游戏版本是不是和Mod要求的版本匹配？
你是在建房间时启用的，还是在游戏开始后启用的？
这个Mod是客户端Mod，服务端Mod，还是要全员安装的Mod？

当你说“我明明启用了Mod但是没效果”，90%的情况是把服务端Mod当作客户端Mod装了——你在本地“Mods”菜单勾选了它，但建房间时没在房间设置里勾选，游戏就认为你只启用了本地加载，并没有把Mod内容放进世界里。特别容易混淆的是：主界面的“Mods”菜单和建房间界面里的“模组设置”是两个不同的开关。

还有10%的情况是真的不兼容。这时候去看游戏日志，最靠谱。

6. 红字报错排查：从日志到修复的完整链路

Mod装多了，谁都免不了遇到红字或闪退。我的态度是：报错不可怕，怕的是你不看日志就删Mod。学会看日志，是最重要的自救技能。

6.1 日志文件在哪

联机版日志路径：

code复制文档\Klei\DoNotStarveTogether\client_log.txt

单机版：

code复制文档\Klei\DoNotStarve\client_log.txt

服务器端的日志也有，通常在主机玩家的同一个Klei目录下，文件名可能是server_log.txt。

打开日志，先别急着搜“ERROR”，先看最后几十行。Lua报错会打印一个带文件路径和行号的堆栈信息，这通常是定位问题的第一线索。

6.2 常见报错类型速查表

我把这几年最常见的报错罗列一下，你对照着排查能省不少时间。

报错关键字	含义	常见原因	排查方向
attempt to index a nil value	试图访问一个空值	Mod引用了不存在的Prefab、组件或全局变量	检查Prefab名称、组件名拼写
Could not find prefab	找不到指定Prefab	新增物品/生物的Prefab文件没加载	检查modmain里的PrefabFiles声明
Could not find anim build	找不到动画资源	SetBuild用了错误的构建名，或动画文件缺失	检查AnimState:SetBuild参数
AddRecipe2: duplicate recipe	配方重复	两个Mod注册了同一个配方ID	换一个配方ID，或确认冲突Mod
api_version mismatch	API版本不匹配	Mod用旧版API写在当前游戏版本上	更新Mod，或降级游戏版本
Bad component name	组件名错误	拼错组件名，或组件未在实体上注册	对照官方组件列表检查

看到“attempt to index a nil value”这个报错，尤其新手容易懵。其实意思是：脚本尝试访问某个不存在的对象。比如你写inst.components.health:SetMaxHealth(200)，但当前实体根本没有health组件，就会报这个错。解决办法是在前面加一个判断：

lua复制if inst.components.health then
    inst.components.health:SetMaxHealth(200)
end

这行判断看着啰嗦，但能避免很多崩溃，是Mod开发里的好习惯。

6.3 一个真实的排查案例

我经历过一个特别典型的案例，拿出来说说。有个朋友反馈，我的一个Mod在他电脑上闪退，但在我这里一切正常。他发来的日志里有这么一段：

code复制scripts/components/equippable.lua:44: attempt to index a nil value (field '?')

第一反应是Mod代码有问题，但我在本地测试了好几遍都没复现。后来让他把完整的文件夹结构截图给我，发现他把整个Mod文件夹复制进mods目录时，少复制了anim子文件夹。护符的动画文件不在，游戏加载实体时找不到动画Build，于是在equippable组件初始化的时候，AnimState返回了空值，导致了索引空值崩溃。

这个案例说明，很多报错其实是资源缺失，而不是逻辑错误。所以排查思路应该是：先确认Mod文件完整，再看代码逻辑，最后才怀疑兼容性。

6.4 多Mod冲突的二分法定位

如果你同时开了几十个Mod，崩溃后很难判断是谁干的。这里我推荐二分法：

第一步，把所有Mod全部关闭。
第二步，开启一半Mod，进游戏测试。
第三步，如果正常，再开启剩下的一半；如果崩溃，关闭当前这一半的一半，重复。

这样操作，通常三四轮就能定位到肇事Mod。这个方法极其朴素，但比瞎猜高效得多。

还有一种情况是两个Mod单独开都正常，同时开就崩溃。这种就是真正的冲突。对策有两个：一个是放弃其中一个，另一个是去创意工坊看看有没有人做了兼容补丁。大型Mod之间经常出兼容补丁，这不算新鲜事。

7. Mod装的多了以后：兼容性与性能优化

如果你从“用Mod”进化到“写Mod”，迟早会关心性能问题。饥荒对Mod的包容度很高，但容纳不代表放任，写得不好的Mod照样会把帧率拖垮，或者把存档搞坏。

7.1 写Mod的黄金法则：别改原Prefab

很多人写Mod，刚开始懒得看API，直接把原版Prefab文件复制一份，改改数值，再替换掉游戏的原文件。这种做法短期内能用，但问题极大：一是游戏更新后原文件变了，你的“魔改版”可能直接失效；二是其他Mod也可能在修改同一个Prefab，互相覆盖，乱成一团。

正确做法是用AddPrefabPostInit钩子。这个API的含义是：游戏先正常加载原Prefab，创建实例，然后执行你注册的函数，你在里面追加修改。

lua复制local GLOBAL = GLOBAL

GLOBAL.AddPrefabPostInit("wilson", function(inst)
    -- 给Wilson额外增加一个健康值恢复组件
    if not inst.components.healthregen then
        inst:AddComponent("healthregen")
        inst.components.healthregen:SetRegenRate(1.0)
    end
end)

这样写的好处是：即使有别的Mod也改了Wilson，你追加的修改依然会被执行，而不是把原文件整个替换掉。这个原则是所有Mod兼容性的基石。

7.2 事件监听和轮询的选择

写Mod时，我见过最常见的性能杀手是“每帧轮询”。有人想在角色HP低时自动回血，写了个OnUpdate函数，每帧都检查一次当前血量。单机这样写问题不大，联机一群人一起跑，服务器CPU很快就爆了。

更好的做法是用事件。当你需要在某件事发生时触发逻辑，先看看游戏有没有对应的事件，比如onhealthchange、onpickup、onattack。有就直接监听，没有才考虑用DoPeriodicTask来做低频轮询。

lua复制inst:ListenForEvent("healthchange", function()
    -- 血量变化时执行逻辑，而不是每帧检查
end)

用事件有一个隐形好处：代码更清晰，别人看你的Mod时能一眼看出触发的时机，而不是在一堆轮询逻辑里猜。

7.3 存档兼容：为什么关掉Mod会让旧档崩

很多玩家不知道，Mod写的Prefab数据会被写进存档。你带一个“温暖护符”存档后退出游戏，这个护符的实体数据就存下来了。下次启动游戏，如果Mod被禁用，游戏读档时遇到一个“不认识的Prefab ID”，处理方式要么是跳过，要么是崩溃，取决于游戏版本和报错位置。

所以我的建议是，玩大型Mod之前，先复制一份原始存档备份。真的，这个习惯能救你很多次。而且重要的事说三遍：备份，备份，备份。

对Mod作者来说，你更新Mod时要格外注意存档兼容性。如果你改变了某个已有的Prefab名称，或者修改了某个组件的数据结构，老存档里的数据可能无法解析，轻则丢失物品，重则读档崩溃。这种情况下，最好在Mod描述里明确写“需要开新档”或“兼容旧存档”。

7.4 给创作者和玩家的更新建议

游戏本体和Mod都在不断更新。作为创作者，我建议每次改动都更新modinfo.lua里的version，并在创意工坊页面写清楚更新内容。玩家端的体验是：你更新了Mod，但旧存档还能不能用、需不需要重新订阅，这些在更新日志里说清楚，能省下大量售后问题。

作为玩家，更新游戏版本前，最好先把常玩的Mod备份一份。Klei大版本更新后，很多旧Mod会出现兼容问题，尤其是那些用了内部API、API版本号还停在前朝的Mod。如果更新游戏后Mod大面积失效，回滚Mod版本往往比回滚游戏版本更实际。

8. 玩Mod这几年，我的一些真实体会

做饥荒Mod这几年，我最大的感受是：Mod社区的核心不是代码，而是“把游戏改造成自己想要的样子”的这种热情。这个游戏厉害的地方在于，它给了玩家一个足够深的修改接口，让所有人都有机会把自己的想法变成可以玩的东西。

我踩过最多的坑，永远不是那些看起来很难的技术问题，而是最基础的地方：没看日志就动手改代码、漏了资源文件、搞混了客户端和服务端。所以如果你刚开始学Mod，我建议你从“把一个Mod装好、看明白它怎么工作”开始，再慢慢进阶到“自己动手改一行代码”。不要一上来就憋一个巨大的Mod，那只会让你在两三天后彻底放弃。

最后分享一个很多人忽略的小技巧：如果你把一个Mod从创意工坊退订了，但存档里还有它生成的物品或建筑，最好在删Mod之前处理掉这些存档里的内容，或者直接开新档。否则旧档轻则物品消失，重则直接读不了。同理，给朋友推荐大Mod时，也提醒他先备份存档。

我自己的流程到现在还是这样：装新Mod前备份存档，修改代码后必看日志，做完一个功能点就停一下测试一下。这套流程很笨，但非常可靠。希望你看完这篇文章后，也能从“为什么崩了”变成“我知道该怎么查了”。

饥荒Mod全攻略：从安装配置到开发排查一次讲透