星露谷物语SMAPI新手必看：从零开始的模组加载器完全指南
【免费下载链接】SMAPI The modding API for Stardew Valley. 项目地址: https://gitcode.com/gh_mirrors/smap/SMAPI
欢迎来到《星露谷物语》的模组世界！SMAPI（Stardew Modding API）是这款游戏最强大的模组加载器，它能帮你轻松安装各种有趣的星露谷物语模组，让农场生活更加丰富多彩。本指南将从基础安装到进阶配置，一步步带你掌握SMAPI的使用方法，即使是电脑新手也能轻松上手。
目录
1. 认识SMAPI：为什么需要它？2. 安装前的准备工作3. 下载与安装SMAPI4. SMAPI目录结构解析5. 配置文件修改指南6. 安装与管理模组7. 常见问题解决8. 进阶学习资源
1. 认识SMAPI：为什么需要它？
SMAPI就像是《星露谷物语》的"模组管家"，它能帮你完成这些重要工作：
✨ 自动加载模组：当你启动游戏时，SMAPI会自动激活所有安装好的模组，无需手动操作 🛡️ 兼容性检查：自动检测并禁用有问题的模组，防止游戏崩溃 🔄 更新提醒：及时告诉你哪些模组有新版本可用 💾 自动备份存档：每天创建游戏存档备份，再也不怕意外丢失进度 🌍 跨平台支持：完美兼容Windows、Mac和Linux系统
简单来说，没有SMAPI，大多数星露谷物语模组都无法正常工作！
2. 安装前的准备工作
在安装SMAPI前，请确保你的电脑满足这些条件：
2.1 系统要求
操作系统：Windows 7/8/10/11、macOS 10.13+或Linux系统已安装游戏：《星露谷物语》（Steam版、GOG版或Epic版均可）游戏版本：建议使用最新版游戏，旧版本可能导致兼容性问题
2.2 准备工作清单
✅ 确认《星露谷物语》已安装并能正常运行 ✅ 找到游戏安装路径（后面会用到） ✅ 确保有稳定的网络连接（用于下载SMAPI和模组） ✅ 关闭任何正在运行的游戏和相关程序
3. 下载与安装SMAPI
3.1 获取SMAPI安装包
你可以通过源码编译的方式获取SMAPI：
打开终端或命令提示符输入以下命令克隆项目仓库： git clone https://gitcode.com/gh_mirrors/smap/SMAPI.git
3.2 安装步骤
根据你的操作系统选择对应的安装方式：
Windows系统
进入SMAPI源码目录中的src/SMAPI.Installer/assets文件夹双击运行 install on Windows.bat 文件按照安装向导提示操作，程序会自动找到游戏路径安装完成后，会在桌面创建"SMAPI启动器"快捷方式
Mac系统
打开终端，导航到SMAPI源码目录输入以下命令： cd src/SMAPI.Installer/assets
chmod +x "install on macOS.command"
./install on macOS.command
按照终端提示完成安装
Linux系统
打开终端，导航到SMAPI源码目录输入以下命令： cd src/SMAPI.Installer/assets
chmod +x "install on Linux.sh"
./install on Linux.sh
按照终端提示完成安装
⚠️ 注意：安装过程中请不要关闭窗口，安装完成后会显示"安装成功"的提示。
4. SMAPI目录结构解析
安装完成后，让我们了解一下SMAPI的文件结构，这对后续管理模组非常重要：
SMAPI/
├── src/ # 源代码文件夹
│ ├── SMAPI/ # SMAPI核心代码
│ ├── SMAPI.Installer/ # 安装程序相关文件
│ └── 其他模块文件夹...
├── docs/ # 项目文档
├── LICENSE.txt # 开源许可协议
└── 其他配置文件...
游戏目录中的重要文件：
StardewModdingAPI.exe：SMAPI启动器（Windows）smapi-internal/：SMAPI的核心配置文件Mods/：存放所有模组的文件夹（最重要的目录！）logs/：日志文件，用于排查问题
5. 配置文件修改指南
SMAPI的主要配置文件是 smapi-internal/config.json，你可以用记事本或任何文本编辑器打开它。以下是一些常用设置：
5.1 修改模组路径
如果你想将模组存放在其他位置，可以修改这个设置：
"modsPath": "Mods", // 默认为"Mods"文件夹，可改为其他路径
5.2 调整日志级别
日志级别控制SMAPI显示多少详细信息：
"consoleLogLevel": "Info", // 可选值：Trace, Debug, Info, Warn, Error, Fatal
5.3 更改备份设置
调整自动备份的保留数量：
"saveBackupCount": 10, // 保留最近10个备份
💡 修改配置后需要重启游戏才能生效。如果不确定如何设置，可以保持默认值不变。
6. 安装与管理模组
6.1 安装模组的步骤
下载模组文件（通常是.zip格式）解压文件，得到一个包含 manifest.json 的文件夹将整个文件夹复制到游戏目录下的 Mods 文件夹中启动SMAPI，模组会自动加载
📌 提示：优质模组通常会包含详细的安装说明，请务必阅读！
6.2 模组文件结构
一个标准的SMAPI模组应该包含这些文件：
模组文件夹/
├── manifest.json # 模组信息文件（必须有！）
├── ModEntry.cs # 模组代码文件（C#模组）
├── assets/ # 图片、音频等资源文件
├── config.json # 模组配置文件（可选）
└── README.md # 模组说明文档（可选）
其中 manifest.json 是最重要的文件，它包含了模组的名称、版本、作者等关键信息。
6.3 启用/禁用模组
不需要删除文件也能临时关闭模组：
打开游戏目录下的 Mods 文件夹将需要禁用的模组文件夹重命名，在前面加上 _ 符号（例如 _Stardew Valley Expanded）重启游戏，该模组就不会被加载了需要重新启用时，去掉前面的 _ 即可
7. 常见问题解决
7.1 游戏无法启动
检查游戏路径：确保SMAPI安装到了正确的游戏目录冲突模组：尝试暂时移走 Mods 文件夹中的所有模组，再逐个添加找出问题模组更新SMAPI：确保使用最新版本的SMAPI
7.2 模组不生效
安装位置错误：模组文件夹必须直接放在 Mods 目录下，不能嵌套存放文件缺失：检查模组文件夹是否包含 manifest.json 文件版本不兼容：查看模组说明，确认是否支持你当前的游戏和SMAPI版本
7.3 出现错误提示
当SMAPI检测到问题时，会在控制台显示错误信息。常见错误及解决方法：
"This mod is not compatible"：模组与当前SMAPI版本不兼容，需要更新模组"Missing dependency"：缺少依赖模组，安装提示中提到的前置模组即可"Corrupted save file"：存档损坏，可使用SMAPI的自动备份恢复（在 Saves/Backup 文件夹中）
7.4 性能问题
如果游戏变卡：
打开 smapi-internal/config.json将 enableTraceLogging 设置为 false减少同时运行的模组数量，特别是大型地图模组
8. 进阶学习资源
掌握了基础使用后，你可以通过这些资源深入学习：
官方文档
SMAPI技术文档：了解SMAPI的工作原理模组开发指南：学习如何创建自己的模组
模组开发入门
模组模板：SMAPI提供了基础的模组项目模板，位于 src/SMAPI.Mods.ConsoleCommands 等目录示例模组：研究官方示例模组的代码，学习最佳实践
社区支持
虽然不能提供外部链接，但你可以搜索"星露谷物语模组社区"找到活跃的玩家和开发者论坛，在那里可以提问、分享经验和获取最新模组资讯。
恭喜你完成了SMAPI的入门学习！现在你已经掌握了安装、配置和管理星露谷物语模组的基本技能。随着你使用SMAPI的深入，会发现更多让游戏变得更有趣的方法。祝你在星露谷的农场生活愉快！
【免费下载链接】SMAPI The modding API for Stardew Valley. 项目地址: https://gitcode.com/gh_mirrors/smap/SMAPI