企业官网建设流程全解析

• 无人机
• 智能硬件

QGroundControl（QGC）是跨平台的开源地面站软件（支持 Windows、macOS、Linux、Android 与 iOS）。当遇到飞行器连接失败、参数无法下载、航线上传中断或固件刷写失败等问题时，最有效的排查手段就是开启日志（Logging）。本文基于 QGC 官方用户手册（docs/en/qgc-user-guide/troubleshooting/console_logging.md）编写，完整覆盖两种日志手段——图形界面中的App Log Viewer与命令行下的--logging/--log-output参数，并结合仓库源码（src/Utilities/QGCCommandLineParser.cc、src/LogManager/LogManager.cc、src/Utilities/Logging/QGCLoggingCategoryManager.cc等）深入讲解其底层原理。阅读完本文，你将能自主采集、筛选、导出 QGC 运行日志，并针对连接、固件、参数、航点等典型故障定位根因。

一、App Log Viewer：图形化的日志诊断入口

App Log Viewer 是 QGC 内置的图形化日志查看器，用于在应用运行时实时观察日志消息，也是大多数场景下最便捷的入口。

1.1 如何打开 App Log Viewer

进入Application Settings（应用设置）> App Log Viewer即可打开日志视图。该页面对应的 QML 实现在 src/AppSettings/AppLogging.qml，界面结构包括：

• 日志表格（TableView）：展示每条日志的类别（Category）、时间戳（Timestamp）、来源（Source）与消息内容（Message）。日志级别不同会以不同颜色区分（Debug 灰色、Info 正文色、Warning 橙色、Critical/Fatal 红色），并在首列显示警示色条（参考_levelColor函数与LogEntry枚举）。
• 过滤器栏（Filter Bar）：提供按级别（All Levels / Debug / Info / Warning / Critical / Fatal）、按类别（All Categories + 已注册类别列表）以及全文搜索过滤，搜索框还支持正则表达式模式（点选.*按钮启用）。
• Categories 按钮：点击后弹出LoggingCategoriesDialog（源码见 src/LogManager/LoggingCategoriesDialog.qml），以树形结构列出所有已注册的日志类别，支持搜索、逐项启用/禁用，以及一键Reset All恢复默认状态。
• Save 按钮：将当前日志导出为文件（支持txt/csv两种格式，可在 Logging 设置页中切换，见 src/AppSettings/pages/Logging.SettingsUI.json）。
• Clear 按钮：清空当前内存中的日志条目；当磁盘写入失败时界面还会出现 "⚠ Disk Error" 提示。

1.2 日志从何而来：Qt 消息系统的完整链路

要理解 App Log Viewer 的价值，需要先明白 QGC 日志的底层机制。QGC 使用 Qt 的QLoggingCategory机制定义模块化日志类别，并在 src/LogManager/LogManager.cc 中通过LogManager::installHandler(bool logOutput)安装自定义 Qt 消息处理器（msgHandler）：

void LogManager::installHandler(bool logOutput) { auto* mgr = new LogManager(); s_echoToStderr.store(logOutput, std::memory_order_release); qSetMessagePattern( QStringLiteral("%{time process}%{if-warning} Warning:%{endif}%{if-critical} Critical:%{endif} %{message} - " "%{category} - (%{function}:%{line})")); s_defaultHandler = qInstallMessageHandler(&LogManager::msgHandler); }

该处理器把每条日志同时送往三个去向：

1. Qt 默认处理器（s_defaultHandler），保证基础输出行为不变；
2. 标准错误输出 stderr（仅当--log-output开启时，由原子标志s_echoToStderr控制）；
3. LogManager 内部模型（LogModel），供 App Log Viewer 的表格实时展示，并异步落盘到AppLog.log。

日志类别注册的起点在 src/Utilities/Logging/QGCLoggingCategoryManager.cc 的registerCategory()：所有源码中以QGC_LOGGING_CATEGORY宏声明的类别（例如QGC_LOGGING_CATEGORY(ADSBTCPLinkLog, "ADSB.ADSBTCPLink")）都会按模块.子模块的点分结构登记进扁平列表与树形模型，从而出现在 Categories 对话框的树中。类别名遵循 "顶层模块.次级模块" 的层级约定，例如Comms.LinkManager、FactSystem.ParameterManager、Vehicle.MultiVehicleManager等，这正是下文常见类别表能够按模块定位故障的基础。

1.3 持久化日志文件：AppLog.log

无论是否开启--log-output，日志消息都会写入应用日志目录下的AppLog.log文件。从 src/LogManager/LogManager.cc 的init()可以看出，日志目录取自应用设置的logSavePath（可在 QGC 的 Application Settings 中配置），且支持磁盘日志开关、文件大小上限（diskLoggingMaxFileSizeMB）与备份文件数量（diskLoggingMaxBackupFiles）等旋转策略。因此即使 QGC 崩溃或终端关闭，AppLog.log中的历史记录依然可用。

二、常见日志类别速查表

QGC 源码中注册了大量细分日志类别。下表汇总了日常故障排查中最高频使用的类别组合、以及它们各自对应的排查场景（与官方文档一致）：

表中的:verbose后缀是 QGC 对同一模块细分级别的典型写法（如Comms.LinkManager:verbose与FactSystem.ParameterManager:debugCacheFailure），在 Categories 对话框中可以按名称精确搜索并单独启用。

三、命令行日志：--logging 与 --log-output

App Log Viewer 适用于应用仍在运行时的情况；若 QGC 直接崩溃、无法正常启动图形界面，就需要改用命令行参数采集日志。

3.1 两个参数如何协同工作

• --logging:full（或--logging:<逗号分隔的类别列表>）：启用指定的日志类别。full表示开启全部类别。
• --log-output：把日志消息额外输出到stderr（在 macOS/Linux 上即终端窗口）。若不添加该参数，消息只会出现在 App Log Viewer 与日志目录的AppLog.log文件中，不会打印到终端。

两者需要配合使用：--logging决定"记录哪些类别"，--log-output决定"是否同时打印到终端"。

3.2 底层实现：命令行解析与类别过滤

命令行参数由 src/Utilities/QGCCommandLineParser.cc 解析，其中定义了：

constexpr QLatin1StringView kOptLogging = QLatin1StringView("logging"); constexpr QLatin1StringView kOptLogOutput = QLatin1StringView("log-output");

解析结果（out.loggingOptions与out.logOutput）在 src/main.cc 中传递：LogManager::installHandler(args.logOutput)控制 stderr 回显，随后LogManager::applyEnvironmentLogLevel()根据环境变量QGC_LOG_LEVEL（取值debug/info/warning/critical/off）设置全局过滤规则。而--logging的类别值则进入QGCLoggingCategoryManager::installFilter(commandLineLoggingOptions)（src/Utilities/Logging/QGCLoggingCategoryManager.cc），其中对full关键字做了专门处理：

if (!categoryList.isEmpty() && categoryList.first() == QStringLiteral("full")) { _commandLineFullLogging = true; } else { for (const QString& category : categoryList) { _commandLineCategories.insert(category.trimmed()); } }

类别过滤器_categoryFilter()在运行时被QLoggingCategory::installFilter()挂接：对每个日志类别，若它在命令行白名单（_commandLineCategories）中、或是其前缀匹配（normalized == cmdCat || normalized.startsWith(cmdCat + '.')），则启用该类别的 Debug/Info 级别输出；反之则关闭。这意味着：

• --logging:Comms.LinkManager只开启Comms.LinkManager类别，且其子类别（如Comms.LinkManager:verbose）也会因前缀匹配被一并开启；
• --logging:full一次性开启全部类别，输出量巨大，适合需要完整调用链的崩溃类问题；
• 多个类别用逗号分隔，例如--logging:Comms.LinkManager,Vehicle.MultiVehicleManager。

仓库测试 test/Utilities/QGCCommandLineParserTest.cc 中也能看到--logging:Vehicle.FTPManager被规范化为--logging Vehicle.FTPManager的用例，印证了该参数的实际解析行为。

3.3 按操作系统启用命令行日志

由于 QGC 是 GUI 应用，不同平台下 stderr 的可见性不同，操作方式也略有差异：

Windows

QGC 在 Windows 上默认没有控制台窗口，因此必须把 stderr重定向到文件才能捕获日志。在命令提示符中执行（安装路径以官方安装器默认值为例）：

cd "%ProgramFiles%\QGroundControl\bin" QGroundControl --logging:full --log-output > "%USERPROFILE%\qgc_log.txt" 2>&1

> "%USERPROFILE%\qgc_log.txt" 2>&1将标准输出与标准错误一并写入当前用户目录下的qgc_log.txt，退出 QGC 后即可直接查看该文件。

macOS

必须从Terminal（位于 应用程序/实用工具）中启动 QGC：

cd /Applications/QGroundControl.app/Contents/MacOS ./QGroundControl --logging:full --log-output

启动后日志会实时打印到 Terminal 窗口，可配合tee或终端回滚缓冲留存。

Linux

在终端中直接运行 AppImage：

./QGroundControl-<arch>.AppImage --logging:full --log-output

<arch>对应实际架构（如x86_64、aarch64），日志同样输出到当前 shell。

3.4 崩溃场景的取证建议

当 QGC 在运行中崩溃时，建议组合使用：

1. 用--logging:full --log-output启动并重放崩溃步骤，将 stderr 重定向到文件（Windows 必须，macOS/Linux 可选）；
2. 同时保留应用日志目录下的AppLog.log作为补充证据——该文件不受终端会话生命周期影响；
3. 按故障类型先从下表（见"常见日志类别速查表"）锁定最小化类别集合，降低日志噪音后再做二次复现，避免full模式的海量输出淹没关键信息。

四、日志排查的完整工作流

结合 App Log Viewer 与命令行两种手段，推荐按如下流程排查 QGC 故障：

1. 先在 GUI 中复现并观察：打开 Application Settings > App Log Viewer，通过 Categories 对话框启用与故障域对应的类别（连接问题用Comms.LinkManager、参数问题用FactSystem.ParameterManager、航线问题用PlanManager.*），在日志表格中按级别与关键字过滤；
2. 必要时导出：点击 Save 将当前日志保存为 txt/csv，便于归档或与开发者分享；
3. 若 GUI 不可用或崩溃：改用命令行方式，按平台执行上文命令，采集 stderr 输出与AppLog.log；
4. 定位根因：根据日志中的类别、消息内容与函数定位信息（日志格式中的(%{function}:%{line})部分）回溯到对应源码模块，例如连接失败时重点查看LinkManager的链路建立日志，参数加载失败时查看ParameterManager的 CRC 与缓存日志。

五、相关资源

• 官方英文文档：docs/en/qgc-user-guide/troubleshooting/console_logging.md
• 命令行参数一览：docs/en/qgc-dev-guide/command_line_options.md
• App Log Viewer 界面实现：src/AppSettings/AppLogging.qml
• 日志分类对话框：src/LogManager/LoggingCategoriesDialog.qml
• 日志采集与落盘：src/LogManager/LogManager.cc
• 类别过滤与注册：src/Utilities/Logging/QGCLoggingCategoryManager.cc
• 命令行解析与测试：src/Utilities/QGCCommandLineParser.cc、test/Utilities/QGCCommandLineParserTest.cc

• 无人机
• 智能硬件