He subido el módulo, pero PrestaShop dice "Unable to install module."

La instalación de un módulo suele fallar porque PrestaShop no puede leer el archivo, no puede escribir los archivos del módulo o el módulo no puede ejecutarse en el servidor actual.

Comprueba primero la estructura del ZIP. El archivo debe contener una única carpeta de módulo en el nivel superior, con el archivo PHP principal del módulo dentro, por ejemplo mymodule/mymodule.php. Un fallo frecuente es subir un ZIP de estilo GitHub que contiene una carpeta envoltorio extra, una carpeta de documentación o una carpeta de módulo anidada en lugar del directorio instalable real del módulo.

zip=module.zip
unzip -Z1 "$zip" | sed -n '1,20p'
unzip -Z1 "$zip" | awk -F/ 'NF{print $1}' | sort -u
find modules -maxdepth 0 -writable -print
php -v
php -m | grep -Ei '^(zip|curl|dom|fileinfo|json|mbstring|openssl|intl)$'
ls -lt var/logs/* 2>/dev/null | head

• Comprueba los límites de subida: el límite efectivo lo controlan upload_max_filesize y post_max_size. Si el ZIP es mayor que cualquiera de esos valores, la subida desde el back office puede fallar antes de que PrestaShop llegue siquiera a instalar el módulo.
• Comprueba los permisos: el directorio modules/ debe poder escribirse por el usuario del servidor web, y los directorios de caché/logs también deben ser escribibles.
• Comprueba la compatibilidad de PHP: una versión incorrecta de PHP o extensiones PHP ausentes como zip, curl, dom, fileinfo, json, mbstring, openssl o intl pueden romper la instalación o las pantallas de configuración.
• Comprueba los logs de PrestaShop: mira en var/logs/, en la página de error del back office y en el log de errores del servidor web/PHP-FPM para ver la excepción real.
• Limpia la caché después de corregir una instalación fallida, porque PrestaShop puede haber cacheado una clase de módulo cargada parcialmente.

Si el módulo aparece en la lista de módulos pero no se instala, probablemente el archivo se extrajo correctamente y el fallo está dentro de la rutina de instalación del módulo. Si no aparece nunca, céntrate primero en la estructura del ZIP, los límites de subida y los permisos del sistema de archivos.

Si la rutina de instalación falla después de que la carpeta ya se haya extraído, primero elimina el módulo instalado a medias desde Module Manager si aparece visible y, después, limpia var/cache/ antes de intentarlo de nuevo. Si la fila del módulo existe en la base de datos pero el back office no puede cargar la página del módulo, no sigas reintentando a ciegas; restaura la copia de seguridad de archivos/base de datos o pide al soporte que revise el paso install() que falló.

Al contactar con soporte, envía el nombre y la versión del ZIP del módulo, tu versión de PrestaShop, la versión de PHP, el texto exacto del error, las últimas líneas de var/logs/prod.log o var/logs/dev.log y si la carpeta del módulo existe ahora en modules/. Eso indica al soporte si el fallo ocurrió durante la subida/extracción o dentro del instalador propio del módulo.