当前位置：首页 > news >正文

终极指南：SMAPI模组清单manifest.json完整配置教程

news 2026/6/4 12:26:47

终极指南：SMAPI模组清单manifest.json完整配置教程

【免费下载链接】SMAPIThe modding API for Stardew Valley.项目地址: https://gitcode.com/gh_mirrors/smap/SMAPI

想要为《星露谷物语》创建模组吗？SMAPI（Stardew Valley Modding API）是星露谷的模组开发框架，而manifest.json文件是你模组的心脏！这份配置文件定义了模组的所有基本信息，让SMAPI知道如何加载和运行你的模组。无论你是完全的新手还是有一定经验的开发者，这篇指南都会带你从零开始，掌握manifest.json的完整配置技巧。

SMAPI代码分析工具示例：显示代码警告和优化建议

为什么manifest.json如此重要？

想象一下你买了一本新书，manifest.json就像是这本书的封面和目录。它告诉SMAPI：

你的模组叫什么名字（Name）
谁创造了它（Author）
版本号是多少（Version）
模组是做什么的（Description）
如何识别这个模组（UniqueID）
如何加载模组（EntryDll或ContentPackFor）

没有正确的manifest.json，SMAPI就不知道如何加载你的模组，玩家也无法使用你的创作！

快速开始：你的第一个manifest.json

让我们从一个最简单的例子开始。创建一个名为manifest.json的文件，放在你的模组项目根目录下：

{ "Name": "我的第一个模组", "Author": "你的用户名", "Version": "1.0.0", "Description": "这是我为星露谷物语创建的第一个模组！", "UniqueID": "YourName.MyFirstMod", "EntryDll": "MyFirstMod.dll" }

这就是最基本的配置！现在让我们详细解释每个字段：

1. 模组基本信息（必填字段）

Name：模组的显示名称，会出现在SMAPI日志和玩家界面中
Author：你的名字或用户名，建议包含发布时用的用户名
Version：版本号，遵循"主版本.次版本.修订号"格式（如1.0.0）
Description：简短描述，一两句话说明模组功能
UniqueID：模组的唯一标识符，格式为"用户名.模组名"，不能有空格

2. 加载方式（二选一）

代码模组（C# DLL）：

"EntryDll": "你的模组.dll"

内容包（资源模组）：

"ContentPackFor": { "UniqueID": "Pathoschild.ContentPatcher", "MinimumVersion": "1.24.0" }

进阶配置：让你的模组更专业

版本兼容性设置

为了让玩家知道你的模组需要什么环境，可以添加这些字段：

{ "MinimumApiVersion": "4.5.2", "MinimumGameVersion": "1.5.6" }

MinimumApiVersion：最低SMAPI版本要求
MinimumGameVersion：最低星露谷物语游戏版本要求

依赖管理

如果你的模组需要其他模组才能运行：

"Dependencies": [ { "UniqueID": "Pathoschild.LookupAnything", "MinimumVersion": "1.29.0", "IsRequired": true }, { "UniqueID": "spacechase0.JsonAssets", "MinimumVersion": "1.10.0", "IsRequired": false } ]

IsRequired：设为false时，依赖缺失只会警告，不会阻止加载

自动更新配置

让SMAPI自动检查更新并通知玩家：

"UpdateKeys": [ "Nexus:5413", "GitHub:Pathoschild/SMAPI", "CurseForge:224230" ]

支持Nexus Mods、GitHub、CurseForge等多个平台！

实用技巧和最佳实践

技巧1：使用项目版本自动同步

在.csproj文件中设置版本号：

<PropertyGroup> <Version>1.2.3</Version> </PropertyGroup>

然后在manifest.json中使用：

{ "Version": "%ProjectVersion%", "MinimumApiVersion": "%ProjectVersion%" }

这样版本号会自动同步，减少手动更新的错误！

技巧2：验证你的配置

SMAPI提供了JSON模式文件来验证你的manifest.json是否正确。在你的manifest.json开头添加：

{ "$schema": "https://smapi.io/schemas/manifest.json", // 其他配置... }

这样在VS Code等编辑器中会实时验证配置，提前发现问题！

技巧3：查看官方示例

学习最好的方式就是看实际的例子。在SMAPI项目中，你可以找到多个示例：

控制台命令模组：src/SMAPI.Mods.ConsoleCommands/manifest.json
存档备份模组：src/SMAPI.Mods.SaveBackup/manifest.json

常见错误和解决方法

错误1：缺少EntryDll或ContentPackFor

错误信息：Missing required field: EntryDll or ContentPackFor

解决方法：确保你正确设置了加载方式。代码模组用EntryDll，内容包用ContentPackFor。

错误2：版本格式不正确

错误信息：Invalid semantic version

解决方法：版本号必须是主版本.次版本.修订号格式，如1.2.3或2.0.0-beta。

错误3：UniqueID格式非法

错误信息：Invalid mod ID

解决方法：只能使用字母、数字、下划线、点和连字符，如YourName.ModName。

使用构建工具简化开发

SMAPI提供了一个强大的NuGet包Pathoschild.Stardew.ModBuildConfig，它可以：

自动检测游戏路径
自动安装和调试模组
创建发布用的ZIP文件
提供代码分析和警告

SMAPI构建工具帮助开发者简化模组开发流程

要使用它，只需在你的项目中引用这个NuGet包，它会自动处理大部分繁琐的配置工作！

实际案例：创建一个完整的模组

让我们创建一个实用的"时间控制"模组：

{ "$schema": "https://smapi.io/schemas/manifest.json", "Name": "时间控制器", "Author": "YourName", "Version": "1.0.0", "Description": "允许玩家控制游戏时间流速的模组", "UniqueID": "YourName.TimeController", "EntryDll": "TimeController.dll", "MinimumApiVersion": "4.5.2", "MinimumGameVersion": "1.5.6", "Dependencies": [ { "UniqueID": "spacechase0.GenericModConfigMenu", "MinimumVersion": "1.5.0", "IsRequired": false } ], "UpdateKeys": ["GitHub:YourName/TimeController"] }

这个模组包含了：