Saltar al contenido principal

Resolución de problemas (FAQ)

Organizado como «síntoma → causa → solución». Fallos de conexión, fallos de autenticación, texto ilegible y variables sin resolver son las cuatro grandes categorías.

Fallos de conexión / envío​

SíntomaCausa probableSolución
Se informa «sin dirección base»El grupo no tiene entorno vinculado, o al entorno le falta la Pre-URL de ese protocoloVincula un entorno, añade la Pre-URL del protocolo
WS/gRPC/MQTT no conectaScheme de Pre-URL incorrecto (el protocolo se clasifica por el scheme)ws usa ws/wss, grpc usa grpc/grpcs, mqtt usa mqtt/mqtts
TCP/UDP no conectaHost y puerto intercambiadosEl host lleva la dirección, el puerto va aparte
Errores TLSScheme cifrado pero sin certificado configuradoImporta un certificado de cliente, o desactiva la verificación TLS si lo necesitas
La conexión larga se corta de repenteSe recupera automáticamente cuando está inactivaReconecta antes de usar; cierra las sesiones antiguas al depurar en serie (el cupo es limitado)

Autenticación (401 / 403)​

SíntomaCausaSolución
401 incluso con tokenEl script de envío previo no se ejecutó (ejecución de scripts desactivada)Confirma que «ejecutar scripts» está activado
{{authToken}} queda literal (sin reemplazar){{}} no puede leer tokens guardados en ejecuciónUsa un script de envío previo con sdk.env.get para inyectar la cabecera (ver recetas, escenario 1)
La siguiente solicitud no obtiene el token tras el loginLas dos solicitudes están en grupos / entornos distintosPonlas en el mismo grupo vinculado al mismo entorno (las variables de ejecución se acotan por entorno)

Texto ilegible / codificación​

SíntomaCausaSolución
Chino ilegible en la respuestaEl servidor devuelve no-UTF-8 (p. ej. GBK)Decodifica con el charset correspondiente; reproduce con /charset/gbk
El descifrado devuelve una cadena Error: ...Cifrado inválido/vacío, o key/iv distinto del cifrado ($crypto solo devuelve cadenas de error, nunca lanza/aborta)Mantén key e iv idénticos al cifrar y descifrar; comprueba si la cadena devuelta empieza por Error: (el texto claro chino va y vuelve bien, verificado)
El script informa Script aborted requestUna excepción JS no capturada en el script (habitual: valores de cabecera no ASCII en headers.set, o acceso a propiedades de undefined)Envuelve las llamadas arriesgadas en try/catch; pon contenido UTF-8 en el body/params de query y mantén los valores de cabecera en ASCII
Resultado base64 extraño en scriptsSe pasó un Uint8Array/bytes a $codec/sdk.utils (se convierte con String() a "97,98,99" antes de codificar)Pasa siempre cadenas; tanto $codec.base64Encode/Decode como sdk.utils.base64Encode/Decode son UTF-8-safe string↔string — elige uno

Los scripts no surten efecto​

SíntomaCausaSolución
El script de envío previo cambió el body pero en la línea no apareceNo hay reescritura por «asignación»request.body = new string (la asignación reemplaza todo el body)
La reescritura post-respuesta no se veCómo reescribirresponse.body = new string; la vista de UI/resultado muestra el nuevo contenido tras reescribir
El script se informa como «sin punto de entrada, omitido»Nombre de función incorrectoDebe llamarse exactamente onRequest / onResponse
Los scripts no se leen valores entre síMecanismo de compartición desconocidoLos scripts de la misma cadena comparten globalThis — pasa valores mediante globalThis.xxx
AES «falló el cifrado» en scriptsForma de argumentos incorrecta$crypto.encryptAES toma cadenas posicionales, no un objeto {text,key,iv}
El script falla con require: 未找到库 [...]La clave de biblioteca es incorrecta, o se renombró/borró una biblioteca de scripts de usuarioCopia la sentencia require desde el gestor de bibliotecas (la forma por identificador sobrevive a los renombrados); las claves integradas son @libs/base64 / @libs/hex; los require en comentarios se ignoran y nunca se empaquetan

Chuleta de resolución de variables​

  • {{name}}: resuelve solo variables de configuración del entorno / de envío; no puede leer valores guardados en tiempo de ejecución por los scripts.
  • Leer variables dentro de scripts: las tres capas son legibles — úsalo para pasar tokens entre solicitudes.
  • Para que los valores extraídos también sirvan a {{}}: activa el ajuste «escribir la extracción de vuelta al entorno».

Detalles: conceptos clave, el sistema de variables.

¿Sigues atascado?​

  • Consigue primero el «caso mínimo funcional» con /echo (HTTP) o /ws/echo (WS) y añade auth/scripts paso a paso.
  • Depura de uno en uno: ¿la solicitud sale del dispositivo? (no conecta → revisa Pre-URL/host/puerto) → ¿se ejecutan los scripts? (¿está activada la ejecución de scripts?) → ¿se resuelven las variables? (¿qué capa?)
  • Los errores de scripts se pueden contrastar con la Referencia de la API de scripts.