模组:制作指南/APIs/Logging

制作SMAPI模组

---

• 入门
• 游戏基本架构
• 测试和疑难解答
• 发布
• SMAPI中的API

  基本API：

  • Mod structure（模组结构）
  • Manifest（清单）
  • Events（事件）
  • Config（配置）
  • Content（内容）
  • Data（数据）
  • Input（输入）
  • Logging（日志）
  • Reflection（反射）
  • Multiplayer（多人）
  • Translation（翻译）
  • Update checks（检查更新）
  • Utilities（工具）

  进阶API:

  • Content packs（内容包）
  • Console（控制台命令）
  • Integrations（模组整合）
  • Harmony

• 更多指南

← 模组:目录

监视接口（monitor API）对应于 this.Monitor 模组类，主要用于向控制台和日志文件写入消息。

日志

概览

您可以通过调用 this.Monitor.Log 并传入一个消息字符串和一个日志级别来记录消息。这些消息会出现在 SMAPI 控制台和日志文件中。

例如，下述代码

this.Monitor.Log("a trace message", LogLevel.Trace);
this.Monitor.Log("a debug message", LogLevel.Debug);
this.Monitor.Log("an info message", LogLevel.Info);
this.Monitor.Log("a warning message", LogLevel.Warn);
this.Monitor.Log("an error message", LogLevel.Error);

会产出一个日志条目，包括时间戳、日志级别、模组名称和消息：

[18:00:00 TRACE NameOfMod] a trace message
[18:00:00 DEBUG NameOfMod] a debug message
[18:00:00 INFO NameOfMod] an info message
[18:00:00 WARN NameOfMod] a warning message
[18:00:00 ERROR NameOfMod] an error message

尽管文本在日志文件中不会显示色彩，但是会在 SMAPI 控制台中显示色彩。

日志级别

日志级别是语义的（semantic），这就是说，级别文本能传达信息（例如 Trace 消息和 Error 消息，顾名思义，有所不同）。您应当使用最接近消息意图的日志级别：

级别	含义
Trace	跟踪信息，面向开发者，常常为低级别的故障排除细节。在他人向您发送其报错日志时较为有用。跟踪信息默认情况下不会出现在控制台窗口中（厨卫您使用的是 "SMAPI for developers"），但会写入日志文件。
Debug	用于解决问题的细节，可能于玩家有关。
Info	与玩家有关的信息。应当审慎使用此级别。
Warn	玩家应当注意的潜在问题。应当较少使用。
Error	提示哪里出错的消息。
Alert	一则重要消息，提示玩家需要进行某些操作（例如更新版本）。主要用于 SMAPI 自身，模组几乎总是不应当使用此级别。

LogOnce

LogOnce 使您能够像上面这样记录一则消息，但每次启动游戏仅记录一次。例如，您可以使用此方法来显示一个接口兼容性警告：

this.Monitor.LogOnce("Some Mod Name used the deprecated X API.", LogLevel.Warn);

冗余日志

您可以使得某一消息仅在 SMAPI 的冗余日志选项开启时才会被记入日志（对于 SMAPI 的 for developers 而言，则是显示在控制台中）。这主要用于在大多数情况下无需记录、但有时需要记录以便排除故障的诊断性信息。

有两种方法来使用它：

// log a TRACE message if verbose logging is enabled
this.Monitor.VerboseLog("This will only appear if verbose logging is enabled.");

// check the verbose option
if (this.Monitor.IsVerbose)
   this.Monitor("This will only appear if verbose logging is enabled.", LogLevel.Trace);

玩家可以向 smapi-internal/StardewModdingAPI.config.json 文件的 VerboseLogging 字段添加相应模组ID来启动荣誉日志。例如，下面代码开启了 SMAPI 和 Content Patcher 的冗余日志：

"VerboseLogging": [ "SMAPI", "Pathoschild.ContentPatcher" ],

问答

创建的日志文件在哪

日志会输出到游戏的 ErrorLogs 数据文件夹。参见 smapi.io/log 以了解如何找到日志文件。您也可以上传日志到此网页以分析之。即使没有错误，日志文件也会被创建和连续写入（因此，您不需要退出游戏就能查看目前为止的日志）。

Modding:Modder Guide/APIs/Logging