Back to Qt.io
Contact Us Blog Download Qt
本页内容

部署 QML Lint 警告和错误

qmllint

qmllint是 Qt 随附的一款工具，用于验证 QML 文件的语法正确性。您可以将 qmllint 集成到构建系统中以便于使用。它还会针对某些 QML 反模式发出警告。有关如何禁用特定警告类型，请参阅《配置 qmllint 警告》。

注意： 使用 IDE（例如Qt Creator ）时， 无需手动运行qmllint 。IDE 会使用 QML Language Server，该工具可在您输入代码时实时提供代码检查结果和诊断信息。

默认情况下，某些问题会触发警告并显示在屏幕上。如果警告数量超过了可通过--max-warnings 配置的限制，则退出代码将不为零。 不过，轻微的问题（例如未使用的导入语句）默认仅作为信息性提示显示，绝不会影响退出代码。qmllint 具有高度可配置性，允许禁用警告或更改其处理方式。

qmllint 会针对以下情况发出警告：

  • 未加修饰的属性访问
  • 未与信号匹配的信号处理程序使用
  • 在 QML 中使用 with 语句
  • 与编译 QML 代码相关的问题
  • 未使用的导入
  • 已弃用的组件和属性
  • 以及许多其他问题

请参阅《QML Lint 警告与错误》了解如何修复 qmllint 警告和错误。

注意：为了使 qmllint 正常工作，它需要类型信息。这些信息由导入路径中的 QML 模块提供。 默认情况下，当前目录以及 Qt 内置类型的导入路径会被用作导入路径。若要添加默认路径中未包含的导入路径，请通过-I 参数进行添加。

要查看所有可用命令行选项的概述和说明，请运行qmllint --help 。

编译器警告

qmllint 可以就无法被qmlsc 编译的代码向您发出警告。

这些警告默认处于禁用状态。若要启用它们，请将 qmllint 配置为使用编译器警告类别。

在 CMake 中使用 qmllint

对于使用qt_add_qml_module()CMake API 创建 QML 模块的项目，系统会自动生成诸如all_qmllint 之类的便捷目标。这些目标会对特定模块或项目中的所有 QML 文件运行 qmllint。

自动应用修复建议

处理 qmllint 发出的警告可能需要相当多的手动编辑和验证工作。qmllint 发出的某些警告会附带相应的修复建议，触发这些建议即可自动解决警告。要触发这些修复建议，您可以：

  • 向 qmllint 传递--fix 。
  • 在您的 IDE 中激活这些修复建议。

一次性在整个项目中应用所有修复建议可能会造成过大的变更。因此，建议将工作分解为更易于管理的部分。您可以通过仅对部分文件进行代码检查，或仅运行特定类别的检查来划分工作。

qmllint --only-explicit-categories --ignore-settings --fix --unqualified=warning <files>

这样将仅对未受限访问应用可用的修复项，同时通过 `--only-explicit-categories ` 和 `--ignore-settings` 禁用所有其他警告类别。

如果您对某项更改不确定，请使用--dry-run 安全地查看运行结果，而无需实际修改文件。

将组件和属性标记为已弃用

qmllint 允许您将属性和组件标记为已弃用：

@Deprecated { reason: "Use NewCustomText instead" }
Text {
    @Deprecated { reason: "Use newProperty instead" }
    property int oldProperty
    property int newProperty
    Component.onCompleted: console.log(oldProperty);  // Warning: XY.qml:8:40: Property "oldProperty" is deprecated (Reason: Use newProperty instead)
}

每次创建组件时，都会显示针对该组件的弃用警告。

内联禁用警告

您可以随时使用 `// qmllint disable` 在文件中临时禁用警告。

当单行代码产生警告时，您可以在该行的末尾这样操作：

Item {
    property string foo
    Item {
        property string bar: foo // qmllint disable unqualified
    }
}

或者，您可以在仅包含 `// qmllint disable` 的行中添加注释，并在该行之后以 `// qmllint enable` 结尾，从而禁用整段行的警告：

Item {
    property string foo
    Item {
        // qmllint disable unqualified
        property string bar: foo
        property string bar2: foo
        // qmllint enable unqualified
    }
}

qmllint 将所有以qmllint 开头的单行注释解释为指令。因此，除非您希望启用或禁用警告，否则请勿以此方式开始注释。

注意：如上例所示， 建议明确指定要禁用的警告或警告列表，而非禁用所有警告。只需在qmllint disable 后列出警告类别即可（名称与--help 中列出的选项相同）。

配置 qmllint 警告

您可以配置 qmllint 发出的警告及其严重级别。这些级别可以是info 、{warning}、error 或disable 。您可以通过.qmllint.ini 配置文件，或向 qmllint 传递命令行选项来自定义警告。命令行选项将覆盖默认设置和配置文件中的设置。

若要通过命令行自定义警告类别的级别，请将相应的命令行选项设置为所需的级别。

例如，要禁用关于弃用项的警告，请使用--deprecated=disable 选项调用qmllint。若要将未使用的导入转换为错误，请传入--unused-imports=error 。

若要更持久地自定义警告，可通过修改配置文件实现。更多详细信息请参阅下文关于Settings 文件的章节。

设置

除了传递命令行选项外，您还可以通过配置文件来配置 qmllint。使用命令行--write-defaults 即可为您生成一个配置文件。

配置文件名为.qmllint.ini ，格式如下：

[General]
DisableDefaultImports=false
MaxWarnings=-1

[Warnings]
AccessSingletonViaObject=warning
AliasCycle=warning
AssignmentInCondition=warning
AttachedPropertyReuse=disable
BadSignalHandlerParameters=warning
Comma=warning
CompilerWarnings=disable
ComponentChildrenCount=warning
ConfusingExpressionStatement=warning
ConfusingMinuses=warning
ConfusingPluses=warning
ContextProperties=warning
Deprecated=warning
DuplicateEnumEntries=warning
DuplicateImport=warning
DuplicateInlineComponent=warning
DuplicatePropertyBinding=warning
DuplicatedName=warning
EnumEntryMatchesEnum=warning
EnumsAreNotTypes=warning
EqualityTypeCoercion=warning
Eval=warning
FunctionUsedBeforeDeclaration=disable
ImportFailure=warning
IncompatibleType=warning
InheritanceCycle=warning
InvalidLintDirective=warning
LintPluginWarnings=disable
LiteralConstructor=warning
MissingEnumEntry=warning
MissingProperty=warning
MissingType=warning
MultilineStrings=info
NonListProperty=warning
NonRootEnum=warning
PreferNonVarProperties=warning
PrefixedImportType=warning
PropertyAliasCycles=warning
QtDesignStudio.FunctionsNotSupportedInQmlUi=warning
QtDesignStudio.ImperativeCodeNotEditableInVisualDesigner=warning
QtDesignStudio.InvalidIdeInVisualDesigner=warning
QtDesignStudio.ReferenceToParentItemNotSupportedByVisualDesigner=warning
QtDesignStudio.UnsupportedRootTypeInQmlUi=warning
QtDesignStudio.UnsupportedTypeInQmlUi=warning
Quick.Anchors=warning
Quick.AttachedPropertyReuse=disable
Quick.AttachedPropertyType=warning
Quick.Color=warning
Quick.ControlsAttachedPropertyReuse=disable
Quick.ControlsNativeCustomize=warning
Quick.LayoutsPositioning=warning
Quick.PropertyChangesParsed=warning
Quick.StateNoChildItem=warning
Quick.UnexpectedVarType=warning
ReadOnlyProperty=warning
RedundantOptionalChaining=warning
RequiredProperty=warning
RestrictedType=warning
StalePropertyRead=warning
TopLevelComponent=warning
TranslationFunctionMismatch=warning
UncreatableType=warning
UnintentionalEmptyBlock=warning
UnqualifiedAccess=warning
UnreachableCode=warning
UnresolvedAlias=warning
UnresolvedType=warning
UnterminatedCase=warning
UnusedImports=info
UseProperFunction=warning
VarUsedBeforeDeclaration=warning
Void=disable
WithStatement=warning

警告级别可设置为info 、warning 、error 或disable ，与命令行选项完全一致。

qmllint 会自动在正在进行代码检查的 QML 文件所在位置查找设置文件。它还会遍历所有父目录以查找该文件，并自动应用其中的设置。 您可以通过使用--ignore-settings 来禁用此行为。您始终可以通过指定命令行参数来覆盖这些默认设置，这些参数的优先级高于设置文件中的警告级别。

上下文属性设置

可以在独立的设置文件中按名称定义或忽略上下文属性。上下文属性设置允许更精细地禁用上下文属性使用中的未限定访问警告，而.qmllint.ini 仅允许禁用所有未限定访问警告，其中可能包括与上下文属性无关的警告。

上下文属性设置文件命名为.contextProperties.ini ，应位于项目的源代码文件夹内。其格式如下：

[General]
disableUnqualifiedAccess = "myContextProperty1,myContextProperty2"
warnOnUsage = "myContextProperty3,myContextProperty4,myContextProperty5"
disableHeuristic = false

若要禁用 qmllint 针对上下文属性名称未加修饰访问的警告，请将该上下文属性名称添加到 `disableUnqualifiedAccess` 中。多个上下文属性名称之间用逗号分隔。

若要对上下文属性的使用发出警告，请将上下文属性名称添加到 `warnOnUsage` 中。多个上下文属性名称之间用逗号分隔。

若要控制 qmllint 的启发式规则，请将 `disableHeuristic ` 设置为 `true ` 或 `false`。

脚本编写

qmllint 可以通过--json <file> 选项写入或输出 JSON，该选项将返回包含警告消息、警告所在的文件和行号以及严重级别的有效 JSON。使用特殊文件名 '-' 可将输出写入标准输出（stdout）而非文件。这可用于更轻松地将 qmllint 集成到您的预提交钩子或持续集成（CI）测试中。

注意： 在处理不可信代码时，应将qmllint 部署在沙箱、容器或其他安全环境中。

另请参阅 “类型描述文件”和“Qt Quick 工具与实用程序”。

部署 QML Lint 警告和错误

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.