故障排查指南

当您在使用 MQTTX 遇到问题时，提供详细的信息可以显著加快解决问题的过程。本指南列出了在大多数故障排查场景中需要收集的基本信息，特别是对于 UI 相关问题、调试 MQTT 数据包或需要访问开发者工具的情况。

需要收集的信息

1. 问题截图 一张清晰描述问题的截图。请确保已隐去任何敏感信息。

2. 复现步骤 提供详细的、一步一步的描述，说明如何稳定地复现该问题。描述越具体，诊断就越容易。

3. 系统和 MQTTX 信息 收集这些信息以帮助了解环境：

• MQTTX 版本: 点击 MQTTX 界面左下角的 "i" 按钮（关于），可以找到版本信息。
• 操作系统: 请说明您的操作系统及其版本（例如，Windows 10 专业版，macOS Sonoma 14.2，Ubuntu 22.04 LTS）。

4. 网络环境 描述您的网络设置：

• 您是否正在使用 VPN、公司代理、Zscaler 或任何其他本地防火墙软件？
• 是否存在任何可能干扰 MQTTX 连接或渲染的特定网络配置？

5. 开发者工具控制台错误 对于 UI 相关问题、白屏、渲染错误或界面中的意外行为，开发者工具控制台非常重要。

• 如何打开开发者工具：
  • 使用快捷键：
    • Windows/Linux: Ctrl + Shift + I
    • macOS: Cmd + Opt + I
  • 使用菜单：
    • 点击顶部菜单 View -> Toggle Developer Tools（切换开发者工具）
• 需要查找的内容：
• 使用控制台：
  • 打开开发者工具后，点击 Console（控制台）标签页。
  • 查找在复现问题时出现的任何错误消息（通常以红色突出显示）或警告。
  • 完整复制并粘贴相关的错误消息。
• 关于开发者工具的重要说明：
  • 默认情况下，MQTTX 不会加载开发者工具，以优化性能并保持较小的应用程序包体积。
  • 开发者工具设计为仅在使用快捷键或菜单明确调用时才加载。这允许在生产环境中进行现场调试，这对于遇到 UI 中的视觉故障或功能障碍时至关重要，从而能够检查网络流量、控制台日志和性能分析。

6. MQTTX 日志 MQTTX 会生成日志，这些日志可以提供其操作和遇到的任何错误的详细信息。

• 日志级别：日志系统会显示四个级别的信息：
  • DEBUG：提供详细的调试信息，包括 MQTT.js 数据包的细节，便于排查问题。
  • INFO：用户操作信息的反馈。
  • WARN：关于不安全操作或潜在风险的警告。
  • ERROR：发生故障时的错误消息。
• 日志文件位置：

  操作系统	日志文件路径
  Linux	~/.config/MQTTX/logs/log
  macOS	~/Library/Application Support/MQTTX/logs/log
  Windows	%USERPROFILE%\AppData\Roaming\MQTTX\logs\log

• 日志轮替：每次关闭 MQTTX 时，当前的日志文件都会根据时间戳重命名（例如 [YY]-[MM]-[DD]T[hh]:[mm].log），并在下次启动时创建一个新的 log 文件。请提供相关的日志文件。

解决白屏或渲染错误

通过快捷键（Ctrl + Shift + I / Cmd + Opt + I）或菜单（View -> Toggle Developer Tools）打开开发者工具的能力对于诊断生产环境中的白屏或意外渲染行为等问题尤为重要。由于出于性能原因默认禁用 DevTools，这些访问方式为用户和贡献者在出现这些问题时直接获取调试信息提供了一种基本机制，从而有助于更快地进行根本原因分析。

通过提供这些信息，您可以帮助开发团队和社区更有效地理解和解决您的问题。