星露谷物语SMAPI新手必看：从零开始的模组加载器完全指南

欢迎来到《星露谷物语》的模组世界！SMAPI（Stardew Modding API）是这款游戏最强大的模组加载器，它能帮你轻松安装各种有趣的星露谷物语模组，让农场生活更加丰富多彩。本指南将从基础安装到进阶配置，一步步带你掌握SMAPI的使用方法，即使是电脑新手也能轻松上手。

目录

• 1. 认识SMAPI：为什么需要它？
• 2. 安装前的准备工作
• 3. 下载与安装SMAPI
• 4. 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：

1. 打开终端或命令提示符
2. 输入以下命令克隆项目仓库：

   git clone https://gitcode.com/gh_mirrors/smap/SMAPI.git
   

3.2 安装步骤

根据你的操作系统选择对应的安装方式：

Windows系统

1. 进入SMAPI源码目录中的src/SMAPI.Installer/assets文件夹
2. 双击运行 install on Windows.bat 文件
3. 按照安装向导提示操作，程序会自动找到游戏路径
4. 安装完成后，会在桌面创建"SMAPI启动器"快捷方式

Mac系统

1. 打开终端，导航到SMAPI源码目录
2. 输入以下命令：

   cd src/SMAPI.Installer/assets
   chmod +x "install on macOS.command"
   ./install on macOS.command
   

3. 按照终端提示完成安装

Linux系统

1. 打开终端，导航到SMAPI源码目录
2. 输入以下命令：

   cd src/SMAPI.Installer/assets
   chmod +x "install on Linux.sh"
   ./install on Linux.sh
   

3. 按照终端提示完成安装

⚠️ 注意：安装过程中请不要关闭窗口，安装完成后会显示"安装成功"的提示。

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 安装模组的步骤

1. 下载模组文件（通常是.zip格式）
2. 解压文件，得到一个包含 manifest.json 的文件夹
3. 将整个文件夹复制到游戏目录下的 Mods 文件夹中
4. 启动SMAPI，模组会自动加载

📌 提示：优质模组通常会包含详细的安装说明，请务必阅读！

6.2 模组文件结构

一个标准的SMAPI模组应该包含这些文件：

模组文件夹/
├── manifest.json  # 模组信息文件（必须有！）
├── ModEntry.cs    # 模组代码文件（C#模组）
├── assets/        # 图片、音频等资源文件
├── config.json    # 模组配置文件（可选）
└── README.md      # 模组说明文档（可选）

其中 manifest.json 是最重要的文件，它包含了模组的名称、版本、作者等关键信息。

6.3 启用/禁用模组

不需要删除文件也能临时关闭模组：

1. 打开游戏目录下的 Mods 文件夹
2. 将需要禁用的模组文件夹重命名，在前面加上 _ 符号（例如 _Stardew Valley Expanded）
3. 重启游戏，该模组就不会被加载了
4. 需要重新启用时，去掉前面的 _ 即可

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 性能问题

如果游戏变卡：

1. 打开 smapi-internal/config.json
2. 将 enableTraceLogging 设置为 false
3. 减少同时运行的模组数量，特别是大型地图模组

8. 进阶学习资源

掌握了基础使用后，你可以通过这些资源深入学习：

官方文档

• SMAPI技术文档：了解SMAPI的工作原理
• 模组开发指南：学习如何创建自己的模组

模组开发入门

• 模组模板：SMAPI提供了基础的模组项目模板，位于 src/SMAPI.Mods.ConsoleCommands 等目录
• 示例模组：研究官方示例模组的代码，学习最佳实践

社区支持

虽然不能提供外部链接，但你可以搜索"星露谷物语模组社区"找到活跃的玩家和开发者论坛，在那里可以提问、分享经验和获取最新模组资讯。

---

恭喜你完成了SMAPI的入门学习！现在你已经掌握了安装、配置和管理星露谷物语模组的基本技能。随着你使用SMAPI的深入，会发现更多让游戏变得更有趣的方法。祝你在星露谷的农场生活愉快！