常见问题

关于Qt Creator 的一些常见问题解答。

您还可以在“已知问题”和“操作指南”部分，或者特定领域的“故障排除”部分（例如“调试”）中找到问题的答案。

一般问题

Qt Creator 随 MinGW 一起提供，我应该将此版本与 Qt 一起使用吗？

请使用与该 Qt 版本配套构建的版本。

Qt Creator 无法找到辅助应用程序，例如 Git、Ninja 或编译器。我该怎么办？

在启动Qt Creator 时，请确保该应用程序位于系统的 PATH 中。此外，请选择“Preferences ”以检查为该应用程序指定的设置。许多插件会指定所需工具的路径或其运行的环境。

您还可以按照“编辑环境设置”中的说明，为全局、特定项目或套件指定查找和运行工具的环境。

当您从桌面（而非终端应用程序）启动Qt Creator 时，这一点尤为重要，例如在 macOS 上通过 Finder、Dock 或 Spotlight 启动，或在 Gnome 环境中通过 Dock、Dash 或“活动概览”启动。 在这种情况下，启动的应用程序不会继承您为 shell（即终端应用程序所使用的）设置的环境，而是从launchd （macOS）或gnome-shell （Gnome）继承环境。 这意味着，如果您是从桌面启动Qt Creator ，那么您为终端设置的路径（例如 macOS 上 Homebrew 的/usr/local/bin 或/opt/homebrew/bin ）将不会自动生效。

已报告的问题是否已得到解决？

您可以在Qt 项目错误跟踪器中查询任何问题。

Qt Widgets 关于 Designer 集成的疑问

为什么在Design 模式下无法加载自定义控件，尽管它们在独立版的Qt Widgets Designer中可以正常工作？

Qt Widgets Designer会从标准位置获取插件，并加载与其构建密钥匹配的插件。独立版和集成版Qt Widgets Designer的插件位置不同。

有关更多信息，请参阅《添加Qt Widgets Designer 插件》。

关于 QML 和Qt Quick 的疑问

为什么我的 QML 导入语句下方会出现红线，尽管我已经安装了该模块？

默认情况下，Qt Creator 会根据 Qt Qml 导入路径查找 QML 模块。有时它可能无法正确识别，您需要手动指定模块的位置。当使用 qmake 作为构建系统时，请在应用程序的.pro 文件中指定QML_IMPORT_PATH 。当使用 CMake 时，请在CMakeLists.txt 文件中添加set 命令。

这同时还能启用 QML 代码的代码补全功能，并消除错误提示。

以下示例演示了如何为 qmake 项目指定导入路径，以确保在针对不同目标平台的构建套件和运行套件之间切换时能够正常工作：

TEMPNAME = $${QMAKE_QMAKE}
MY_QTPATH = $$dirname(TEMPNAME)
QML_IMPORT_PATH += $$MY_QTPATH/../qml
message("my QML Import Path: "$$QML_IMPORT_PATH)

有关如何为 CMake 项目设置导入路径的更多信息，请参阅《导入 QML 模块》。

当Qt Creator 提示缺少 OpenGL 支持时，我该怎么办？

Qt Creator 的某些组件（例如QML Profiler ）使用Qt Quick 2，该组件依赖于OpenGL API进行绘制。遗憾的是，使用OpenGL可能会引发问题，尤其是在远程环境中或驱动程序过时的情况下。在这些情况下，Qt Creator 会在控制台显示与OpenGL相关的错误消息，或将其记录在Windows调试器日志中。

具体的修复方法和解决策略因您的系统环境而异。作为最后手段，您可以禁用受影响的插件。

虚拟机

请尝试在虚拟机设置中启用3D 加速。对于 VirtualBox，还请确保已安装“Guest Addons”（包括实验性的Direct3D 支持）。

Windows

默认情况下，Qt Quick 使用 Direct3D 11。如果遇到问题，请尝试更新显卡驱动程序或升级 DirectX 版本。运行dxdiag.exe 以检查Direct3D 加速是否确实已启用。

您还可以尝试将QSG_RHI_BACKEND 环境变量设置为vulkan 或opengl 。详情请参阅《Qt for Windows - 图形加速》。

Unix

运行glxgears 可快速检查 OpenGL 是否正常工作。查看glxinfo 的输出以获取更多详细信息，例如 OpenGL 驱动程序和渲染器（在应用程序的输出中搜索“OpenGL”）。

如果您使用的是Mesa驱动程序，可以通过设置LIBGL_ALWAYS_SOFTWARE 环境变量，强制OpenGL采用软件渲染。

禁用插件

你可以禁用Qt Creator 中的插件，但会因此牺牲部分功能：

• 在命令行中以 `-noload QmlProfiler -noload QmlDesigner ` 参数启动 `Qt Creator `。
• 通过选择“Help ”>“About Plugins ”来永久禁用插件。

帮助问题

缺少 Qt API 参考文档，且上下文帮助无法找到相关主题。我该怎么办？

请使用以下命令安装 Qt 版本及 Qt 文档： Qt Online Installer。

要查看已安装的文档（.qch 文件）并添加文档，请转至“Preferences ” > “Help ” > “Documentation ”。有关更多信息，请参阅“添加外部文档”。

调试器相关问题

有关调试器故障排除的信息，请参阅“调试器故障排除”。

如果我有多个 GDB 版本可供选择，应该使用哪个？

在 Linux 和 Windows 系统上，请使用安装Qt Creator 和 Qt 时一并安装的、支持 Python 的 GDB 版本。在 macOS 系统上，GDB 已不再受官方支持。若要自行构建支持 Python 的 GDB，请按照QtCreator 构建 GDB 中的说明进行操作。

您必须使用 Python 2.6 或 2.7 版本。

有关更多信息，请参阅“受支持的调试器”。

如何在Qt Creator 中生成核心文件？

要在调试过程中触发生成核心文件的 GDB 命令，请转至“View ” > “Views ” >“Debugger Log”。在“Command ”字段中，输入gcore 并按Enter 键。核心文件将创建在当前工作目录中。您还可以将文件的存储位置（包括相对路径或绝对路径）作为命令的参数进行指定。

关于编译器的问题

如何在Qt Creator 中充分利用多核CPU？

在 Linux 和 macOS 上，进入Projects 模式，在“Build Settings ”中选择您的配置，找到“Build Steps ”，并添加以下值，其中<num> 是您 CPU 的核心数：-j <num>

在 Windows 上，nmake 不支持-j 参数。您可以改用jom。您可以从Qt Downloads 页面下载 jom 的预编译版本：jom。将jom.exe 放置在 %PATH% 路径下的某个位置。进入Build Settings ，并将jom.exe 设置为 make 命令。

关于 Qt 安装的问题

我无法在通过二进制包安装的 Qt 中使用 QSslSocket。该怎么办？

二进制包中的 Qt 是定义了 QT_NO_OPENSSL 后构建的。可以重新构建它。有关更多信息，请参阅Qt Centre：QSsl。

在 Ubuntu 或 Debian 系统上需要哪些发行版的开发包？

sudo apt-get install libglib2.0-dev libsm-dev libxrender-dev libfontconfig1-dev libxext-dev

如果您使用 QtOpenGL，还需安装：

sudo apt-get install libgl-dev libglu-dev

与平台相关的问题

在Qt Creator 中，应用程序的输出显示在何处？

在 Unix（Linux 和 macOS）系统上： qDebug() 及其相关函数使用标准输出和错误输出。运行或调试应用程序时，您可以在“应用程序输出”中查看输出内容。

对于需要用户输入的控制台应用程序，请选择“Projects ” > “Run Settings ” > “Run in terminal ”。若要指定要使用的终端，请选择“Preferences ” > “Environment ” > “System ”。若要使用内部终端，请选择“Preferences ” > “Terminal ” > “Use internal terminal ”。

在 Windows 上： 控制台应用程序和GUI 应用程序的输出显示方式不同。

对于 qmake 项目，.pro 文件中的CONFIG += console 设置指定该应用程序将作为使用其他运行时的控制台应用程序进行构建。

这是 CMake 项目的标准行为。要在 Windows 上创建 GUI 应用程序或在 macOS 上创建应用程序包，必须在CMakeLists.txt 文件中为qt_add_executable命令指定WIN32 或MACOSX_BUNDLE 属性。

运行控制台应用程序时，您可以在调用应用程序的控制台窗口中查看输出。如果调用应用程序是 GUI 应用程序（例如，Qt Creator 的发布版），则会打开一个新的控制台窗口。对于此类应用程序，qDebug() 及其相关函数将使用标准输出和错误输出。

对于控制台应用程序，建议您选择“Projects ” > “Run Settings ” > “Run in terminal ”。

对于GUI应用程序，qDebug() 及其相关函数会使用Windows API函数OutputDebugString() 。输出内容将显示在Application Output 中。但是，为了正确显示输出，Qt Creator 每次只能显示一个来源的输出。您可以使用外部调试输出查看器（例如Windows版的DebugView）来显示GUI应用程序的输出。

关于新功能的问题

请求的功能会实现吗？

如果是计划中的功能，您可以在任务跟踪器中查看相关信息。如果该功能已经实现，则会在即将发布的版本的更改日志中提及。

为什么Qt Creator 默认不为编辑器启用标签页？

以下是我们不默认使用标签页的主要原因：

• 标签页不具备可扩展性。当您打开 5 到 6 个编辑器时，它们运行良好；但打开 10 个时就会变得笨拙；如果需要比标签栏更宽的水平空间，界面将完全无法正常工作。
• 标签页无法适应您的工作集。
• 常见的解决方案是让用户能够重新排列标签页顺序。这样一来，用户就不得不花时间管理标签页，而不是编写代码。
• 标签页迫使你限制打开的编辑器数量，否则会让人感到困惑。

请考虑以下用例：开发人员希望切换编辑器。

事实上，开发者并不想切换编辑器，但为了完成任务可能不得不这样做。我们需要弄清楚这些任务是什么，以便在开发者执行任务时为他们提供更好的导航方式。

许多用例中存在一个共同点：在处理一组已打开的文件时切换编辑器。在处理文件 A 和 B 时，用户有时需要查看文件 C。他们可以使用Ctrl+Tab在文件之间切换，系统会根据文件类型将文件在相应的编辑器中打开。列表按最近使用顺序排序。

通常，用户还会同时处理多个相关的类或函数，即使它们定义或声明在不同的文件中。Qt Creator 为此提供了两个快捷键：F2可追踪光标下的符号，Ctrl+Shift+U可查找该符号的引用。

此外，开发人员还可以：

• 按F4在头文件和源文件之间切换。
• 按Alt+向左键在导航历史记录中向后移动。
• 使用定位器（Ctrl+K）直接告诉Qt Creator 跳转到何处。

定位器可用于打开文件，但打开文件也仅仅是完成某项任务过程中的一个步骤。例如，考虑以下用例：修复来自 someclass.cpp/someclass.h 中的 SomeClass 类中的 AFunction 函数。

在采用标签页界面的情况下，开发人员会在标签栏中搜索“someclass.cpp ”，然后搜索“::AFunction ”，结果却发现该函数并不位于该文件中。接着，他们会在标签栏中搜索“someclass.h ”，发现该函数是内联的，修复问题后，便忘记了自己是从哪里过来的。

借助Qt Creator ，开发者只需输入Ctrl+K m AFun 即可找到该函数。通常，他们只需输入函数名的 3 到 4 个字符。随后，他们可以修复问题，并按Alt+Back返回原位置。

其他定位器筛选器包括：c （用于类）、: （用于所有符号）以及. （用于当前文件中的符号）。

在已打开的文档之间切换的另一种方法是在“Open Documents ”视图中选择目标文档。

如果您仍然希望在编辑器中使用标签页，请转到Preferences >Environment >Interface ，然后选择Use tabbed editors 。