En esta página

Depuración de aplicaciones QML

Al desarrollar una aplicación con QML, existen muchas formas de depurar los posibles problemas con los que te puedas encontrar. En las secciones siguientes se describen las herramientas de depuración disponibles y cómo utilizarlas.

API de la consola

CaracterísticaDescripción
RegistroUtiliza console.log, console.debug, console.info, console.warn o console.error para mostrar información de depuración en la consola.

Por ejemplo:

function f(a, b) {
  console.log("a is ", a, "b is ", b);
}

La salida se genera mediante los métodos qCDebug, qCWarning o qCCritical en C++, con una categoría de qml o js, dependiendo del tipo de archivo que realice el registro.

Véase también «Técnicas de depuración».

Assertconsole.assert comprueba que una expresión sea verdadera. De no ser así, escribe un mensaje opcional en la consola y muestra el seguimiento de la pila.

Por ejemplo:

function f() {
  var x = 12
  console.assert(x == 12, "This will pass");
  console.assert(x > 12, "This will fail");
}
Timerconsole.time y ` console.timeEnd ` registran el tiempo (en milisegundos) transcurrido entre las llamadas. Ambas aceptan un argumento de cadena que identifica la medición.

Por ejemplo:

function f() {
    console.time("wholeFunction");
    console.time("firstPart");
    // first part
    console.timeEnd("firstPart");
    // second part
    console.timeEnd("wholeFunction");
}
Traceconsole.trace imprime el seguimiento de la pila de la ejecución de JavaScript en el punto en el que se llamó. Esta información del seguimiento de la pila contiene el nombre de la función, el nombre del archivo, el número de línea y el número de columna. El seguimiento de la pila se limita a los últimos 10 marcos de la pila.
Countconsole.count muestra el número actual de veces que se ha ejecutado un fragmento de código concreto, junto con un mensaje.

Por ejemplo:

function f() {
  console.count("f called");
}

El ejemplo de código anterior muestra « f called: 1 », « f called: 2 »... cada vez que se ejecuta « f() ».

Profileconsole.profile activa los perfiladores de QML y JavaScript. No admite llamadas anidadas y muestra una advertencia en la consola.
ProfileEndconsole.profileEnd desactiva los perfiladores de QML Profiler y JavaScript. Si se llama a esta función sin haber llamado previamente a console.profile, se muestra una advertencia en la consola. Es necesario haber conectado un cliente de perfilado antes de esta llamada para recibir y almacenar los datos de perfilado.

Por ejemplo:

function f() {
    console.profile();
    //Call some function that needs to be profiled.
    //Ensure that a client is attached before ending
    //the profiling session.
    console.profileEnd();
}
Exceptionconsole.exception muestra un mensaje de error. Funciona igual que console.error, pero requiere al menos un argumento y, además, muestra un seguimiento de la pila de la ejecución de JavaScript en el punto en el que se invoca.

Como alternativa, se puede pasar un objeto ` logging category ` como primer argumento a cualquiera de estas funciones ` console `. Consulte LoggingCategory para obtener más detalles.

Depuración de importaciones de módulos

Establece la variable de entorno QML_IMPORT_TRACE para habilitar la salida de depuración de los mecanismos de carga de importaciones de QML.

Por ejemplo, para un archivo QML sencillo como este:

import QtQuick

Rectangle { width: 100; height: 100 }

Si configuras QML_IMPORT_TRACE=1 antes de ejecutar la herramienta «QML Runtime » o tu aplicación QML C++, verás una salida similar a esta:

QQmlImportDatabase::addImportPath "/qt-sdk/imports"
QQmlImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS"
QQmlImportDatabase::addToImport 0x106237370 "." -1.-1 File as ""
QQmlImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as ""
QQmlImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle"

Infraestructura de depuración de QML

El Qt Qml módulo ofrece servicios para depurar, inspeccionar y analizar el rendimiento de las aplicaciones a través de un puerto TCP o un socket local.

Nota: Los complementos de qmltooling necesarios para la depuración y el análisis de rendimiento de aplicaciones QML en dispositivos se instalan automáticamente durante la instalación de Qt. Deben implementarse en los dispositivos para que la depuración y el análisis de rendimiento funcionen.

Activación de la infraestructura

Al compilar la aplicación, debes habilitar explícitamente la infraestructura de depuración.

Si utilizas CMake, puedes pasar ` -DCMAKE_CXX_FLAGS_INIT=-DQT_QML_DEBUG ` como argumento a ` cmake ` en la línea de comandos para habilitarla solo para una compilación específica. También puedes habilitarla de forma permanente en tu archivo `CMakeLists.txt` añadiendo el siguiente fragmento de código:

qt_add_executable(MyApp
...
)

target_compile_definitions(MyApp PRIVATE QT_QML_DEBUG)

Si utilizas qmake, puedes añadir los parámetros de configuración « CONFIG+=qml_debug » al archivo « .pro » del proyecto o pasarlos como argumento en la línea de comandos.

Si utilizas otro sistema de compilación, deberás pasar la definición ` QT_QML_DEBUG ` al compilador mediante los medios propios de dicho sistema.

Nota: Habilitar la infraestructura de depuración puede comprometer la integridad de la aplicación y del sistema; por lo tanto, solo debe habilitarse en un entorno controlado. Cuando la infraestructura está habilitada, la aplicación muestra la siguiente advertencia:
QML debugging is enabled. Only use this in a safe environment.

Inicio de aplicaciones

Para habilitar la depuración —desde el inicio o para conectar un depurador más adelante—, inicia la aplicación con los siguientes argumentos:

-qmljsdebugger=port:<port_from>[,port_to][,host:<ip address>][,block][,file:<local socket>][,services:<comma-separated list of services to enable>]

Donde:

  • el parámetro obligatorio « port_from » especifica el puerto de depuración o el puerto inicial de un rango de puertos cuando se especifica « port_to »
  • el parámetro opcional « ip address » especifica la dirección IP del host en el que se ejecuta la aplicación
  • el parámetro opcional « block » impide que la aplicación se ejecute hasta que el cliente de depuración se conecte al servidor
  • el parámetro opcional « file » especifica el socket local.
  • el parámetro opcional « services » especifica los servicios que se deben habilitar; por defecto, se habilitan todos los que se encuentren. Ten en cuenta que el servicio « v4 debug » desactiva el JIT.

Una vez que la aplicación se ha iniciado correctamente, muestra el siguiente mensaje:

QML Debugger: Waiting for connection on port <port_number>

o

QML Debugger: Connecting to socket at <file>

Conexión a aplicaciones

Cuando la aplicación está en ejecución, un IDE o una herramienta que implemente el protocolo binario puede conectarse al puerto abierto.

La depuración con Qt Creator

Qt Creator utiliza la infraestructura de depuración para depurar, inspeccionar y perfilar aplicaciones QML tanto en el escritorio como en dispositivos remotos. Qt Creator proporciona clientes integrados para depurar JavaScript, inspeccionar el árbol de objetos y perfilar las actividades de un motor QML. Para obtener más información, consulta Qt Creator: Depuración de proyectos Qt Quick .

La depuración con Qt Extension for Visual Studio Code

Qt Extension for Visual Studio Code ofrece clientes integrados para depurar JavaScript y realizar perfiles de la actividad del motor QML. Para obtener más información, consulte Qt Extension for Visual Studio Code: Depurar aplicaciones Qt Quick .

© 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.