545 líneas
12 KiB
Markdown
545 líneas
12 KiB
Markdown
# Guía de Solución de Problemas (Troubleshooting)
|
|
|
|
Esta guía te ayudará a resolver problemas comunes al usar Classic Add-ons Archive v3.0.
|
|
|
|
## 📋 Índice
|
|
|
|
1. [Problemas de Instalación](#problemas-de-instalación)
|
|
2. [Problemas con la Base de Datos](#problemas-con-la-base-de-datos)
|
|
3. [Problemas de Navegación](#problemas-de-navegación)
|
|
4. [Problemas de Rendimiento](#problemas-de-rendimiento)
|
|
5. [Errores en la Consola](#errores-en-la-consola)
|
|
6. [Incompatibilidades](#incompatibilidades)
|
|
7. [Obtener Ayuda](#obtener-ayuda)
|
|
|
|
---
|
|
|
|
## Problemas de Instalación
|
|
|
|
### El icono de la extensión no aparece
|
|
|
|
**Síntomas:**
|
|
- No veo el icono en la barra de herramientas
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Recargar la extensión:**
|
|
- Firefox: `about:debugging` > Click en "Recargar"
|
|
- Chrome: `chrome://extensions/` > Click en el icono de recargar ↻
|
|
|
|
2. **Verificar que está habilitada:**
|
|
- Firefox: `about:addons` > Extensiones > Buscar "Classic Add-ons Archive"
|
|
- Chrome: `chrome://extensions/` > Buscar la extensión y verificar que el toggle está activado
|
|
|
|
3. **Verificar manifest.json:**
|
|
```bash
|
|
cat manifest.json | grep -A 5 browser_action
|
|
```
|
|
Debe existir la sección `browser_action` con iconos válidos.
|
|
|
|
### Error al cargar la extensión
|
|
|
|
**Error:** "There was an error during installation"
|
|
|
|
**Causas comunes:**
|
|
- `manifest.json` inválido
|
|
- Archivos requeridos faltantes
|
|
- Permisos incorrectos
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Validar el manifest:**
|
|
```bash
|
|
# Instalar web-ext si no lo tienes
|
|
npm install -g web-ext
|
|
|
|
# Validar
|
|
web-ext lint
|
|
```
|
|
|
|
2. **Verificar archivos requeridos:**
|
|
```bash
|
|
ls -la manifest.json background.js
|
|
ls -la content/ca-archive.html content/ca-archive.js content/db-webext.js
|
|
ls -la skin/logo.png skin/button.png
|
|
```
|
|
|
|
3. **Verificar sintaxis JSON:**
|
|
- Usar herramienta online: https://jsonlint.com/
|
|
- O con python:
|
|
```bash
|
|
python3 -m json.tool manifest.json > /dev/null
|
|
```
|
|
|
|
### Firefox: "This add-on could not be installed because it appears to be corrupt"
|
|
|
|
**Solución:**
|
|
|
|
1. Reconstruir el paquete:
|
|
```bash
|
|
./build.sh
|
|
```
|
|
|
|
2. Verificar integridad:
|
|
```bash
|
|
unzip -t dist/ca-archive-3.0.0.xpi
|
|
```
|
|
|
|
3. Si persiste, cargar sin empaquetar:
|
|
- `about:debugging` > Cargar complemento temporal
|
|
- Seleccionar `manifest.json` directamente
|
|
|
|
---
|
|
|
|
## Problemas con la Base de Datos
|
|
|
|
### "Loading database for the first time" se queda cargando
|
|
|
|
**Síntomas:**
|
|
- Mensaje de carga de DB sin terminar
|
|
- Página en blanco
|
|
|
|
**Causas:**
|
|
- Base de datos muy grande
|
|
- Falta archivo SQLite
|
|
- Error de red (si carga desde CDN)
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Verificar que existe el archivo DB:**
|
|
```bash
|
|
ls -lh content/db/*.sqlite
|
|
```
|
|
|
|
2. **Verificar tamaño de la DB:**
|
|
```bash
|
|
du -h content/db/*.sqlite
|
|
```
|
|
Si es >50MB, puede tardar en el primer acceso.
|
|
|
|
3. **Revisar la consola del navegador** (`F12` > Console):
|
|
- Buscar errores relacionados con fetch o sql.js
|
|
|
|
4. **Limpiar storage y reintentar:**
|
|
```javascript
|
|
// En la consola del navegador
|
|
browser.storage.local.clear()
|
|
// o en Chrome:
|
|
chrome.storage.local.clear()
|
|
```
|
|
|
|
5. **Verificar permisos del archivo:**
|
|
```bash
|
|
chmod 644 content/db/*.sqlite
|
|
```
|
|
|
|
### Error: "Could not load SQL engine"
|
|
|
|
**Causa:** sql.js no se pudo cargar
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Verificar conexión a internet** (si usa CDN)
|
|
|
|
2. **Descargar sql.js localmente:**
|
|
```bash
|
|
cd content/
|
|
wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.js
|
|
wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.wasm
|
|
```
|
|
|
|
3. **Actualizar rutas en `db-webext.js`:**
|
|
```javascript
|
|
// Cambiar:
|
|
locateFile: file => `https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/${file}`
|
|
|
|
// Por:
|
|
locateFile: file => browser.runtime.getURL(`content/${file}`)
|
|
```
|
|
|
|
4. **Agregar archivos a `web_accessible_resources` en manifest.json:**
|
|
```json
|
|
"web_accessible_resources": [
|
|
"content/*.wasm",
|
|
"content/sql-wasm.js"
|
|
]
|
|
```
|
|
|
|
### Error: "Database has just been updated, not ready or corrupted!"
|
|
|
|
**Causa:** Archivo SQLite corrupto o inaccesible
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Verificar integridad de la DB:**
|
|
```bash
|
|
sqlite3 content/db/ca-archive-*.sqlite "PRAGMA integrity_check;"
|
|
```
|
|
Debe retornar "ok"
|
|
|
|
2. **Re-descargar la base de datos:**
|
|
- Si tienes repositorio Git: `git checkout content/db/*.sqlite`
|
|
- O descargar manualmente desde releases
|
|
|
|
3. **Permisos de lectura:**
|
|
```bash
|
|
chmod 644 content/db/*.sqlite
|
|
```
|
|
|
|
---
|
|
|
|
## Problemas de Navegación
|
|
|
|
### Los enlaces no funcionan
|
|
|
|
**Síntomas:**
|
|
- Click en categoría/addon no hace nada
|
|
- URL no cambia
|
|
- Página en blanco
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Verificar hash routing:**
|
|
- La URL debe ser: `moz-extension://[id]/content/ca-archive.html#list`
|
|
- No debe ser: `caa:list` (eso es legacy)
|
|
|
|
2. **Revisar consola JavaScript** (`F12`):
|
|
- Buscar errores en `ca-archive.js`
|
|
|
|
3. **Verificar que los módulos se cargan:**
|
|
```javascript
|
|
// En la consola del navegador
|
|
console.log(typeof List, typeof Addon, typeof DB);
|
|
// Debe mostrar los tipos de objeto/function
|
|
```
|
|
|
|
4. **Limpiar caché del navegador:**
|
|
- Firefox: `Ctrl+Shift+Del` > Marcar "Caché"
|
|
- Chrome: `Ctrl+Shift+Del` > "Cached images and files"
|
|
|
|
### Búsqueda no funciona
|
|
|
|
**Síntomas:**
|
|
- Campo de búsqueda no responde
|
|
- No muestra resultados
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Verificar que la DB está cargada:**
|
|
- Debe haber completado la carga inicial
|
|
- Revisar que no hay mensajes de error en consola
|
|
|
|
2. **Verificar el formulario:**
|
|
```html
|
|
<form id="search" action="#list">
|
|
```
|
|
Debe tener `action="#list"` (no `caa:list`)
|
|
|
|
3. **Probar búsqueda directa:**
|
|
- Navegar manualmente a: `#list?q=tu-búsqueda`
|
|
|
|
---
|
|
|
|
## Problemas de Rendimiento
|
|
|
|
### La extensión es lenta
|
|
|
|
**Síntomas:**
|
|
- Navegación lenta entre páginas
|
|
- La UI se congela
|
|
- Alta uso de CPU/RAM
|
|
|
|
**Causas:**
|
|
- Base de datos muy grande en memoria
|
|
- Consultas SQL no optimizadas
|
|
- Demasiados addons en listado
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Verificar uso de memoria:**
|
|
- Firefox: `about:performance`
|
|
- Chrome: `chrome://process-internals/`
|
|
|
|
2. **Reducir resultados por página:**
|
|
- Editar módulos que hacen consultas (list.js, addon.js)
|
|
- Agregar límite LIMIT a queries SQL
|
|
|
|
3. **Considerar IndexedDB en lugar de sql.js:**
|
|
- sql.js carga toda la DB en RAM
|
|
- IndexedDB maneja datos en disco de forma nativa
|
|
|
|
4. **Cerrar otras extensiones:**
|
|
- Conflictos con otras extensiones pueden causar lentitud
|
|
|
|
### Carga inicial muy lenta (>30 segundos)
|
|
|
|
**Causa:** Base de datos grande descargándose por primera vez
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Paciencia:** Primera carga es normal que tarde
|
|
- DB de ~50MB puede tardar 30-60s en redes lentas
|
|
|
|
2. **Verificar progreso:**
|
|
- Abrir Network tab (`F12` > Network)
|
|
- Buscar descarga del archivo .sqlite
|
|
|
|
3. **Pre-cargar la DB:**
|
|
- Copiar manualmente a storage:
|
|
```javascript
|
|
// Demasiado complejo, mejor esperar carga natural
|
|
```
|
|
|
|
4. **Usar conexión más rápida** para primera instalación
|
|
|
|
---
|
|
|
|
## Errores en la Consola
|
|
|
|
### "ReferenceError: DB is not defined"
|
|
|
|
**Causa:** `db-webext.js` no se cargó antes de `ca-archive.js`
|
|
|
|
**Solución:**
|
|
|
|
Verificar orden en `ca-archive.html`:
|
|
```html
|
|
<!-- CORRECTO: -->
|
|
<script src="db-webext.js"></script>
|
|
<script src="ca-archive.js"></script>
|
|
|
|
<!-- INCORRECTO: -->
|
|
<script src="ca-archive.js"></script>
|
|
<script src="db-webext.js"></script>
|
|
```
|
|
|
|
### "Failed to load script: versions.js"
|
|
|
|
**Causa:** Módulo no existe o ruta incorrecta
|
|
|
|
**Soluciones:**
|
|
|
|
1. **Verificar que existe:**
|
|
```bash
|
|
ls -la content/versions.js
|
|
```
|
|
|
|
2. **Verificar permisos:**
|
|
```bash
|
|
chmod 644 content/*.js
|
|
```
|
|
|
|
3. **Verificar en web_accessible_resources** (manifest.json):
|
|
```json
|
|
"web_accessible_resources": [
|
|
"content/*.js"
|
|
]
|
|
```
|
|
|
|
### "Unsafe attempt to load URL"
|
|
|
|
**Causa:** Violación de Content Security Policy
|
|
|
|
**Solución:**
|
|
|
|
Actualizar CSP en manifest.json:
|
|
```json
|
|
"content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self'"
|
|
```
|
|
|
|
**Nota:** `'unsafe-eval'` es necesario para sql.js (WebAssembly).
|
|
|
|
### "TypeError: Cannot read property 'openDB' of undefined"
|
|
|
|
**Causa:** Variable `DB` no está definida globalmente
|
|
|
|
**Solución:**
|
|
|
|
En `db-webext.js`, verificar al final:
|
|
```javascript
|
|
if (typeof window !== "undefined") {
|
|
window.DB = DB;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Incompatibilidades
|
|
|
|
### No funciona en Firefox 56 o inferior
|
|
|
|
**Explicación:**
|
|
- v3.0 requiere Firefox 57+ (WebExtensions puras)
|
|
- Firefox 56 y anteriores usan sistema legacy
|
|
|
|
**Solución:**
|
|
- Usar la versión 2.x para Firefox ≤56
|
|
- O actualizar Firefox a versión moderna
|
|
|
|
### No funciona en Pale Moon / Basilisk
|
|
|
|
**Explicación:**
|
|
- Estos navegadores no soportan WebExtensions completas
|
|
- Usan sistema legacy de Firefox
|
|
|
|
**Solución:**
|
|
- Usar la versión 2.x legacy
|
|
- No hay planes de portar v3 a estos navegadores
|
|
|
|
### Problemas en Chrome con storage
|
|
|
|
**Error:** "QUOTA_BYTES quota exceeded"
|
|
|
|
**Causa:** Base de datos muy grande para storage.local de Chrome (límite 10MB)
|
|
|
|
**Solución:**
|
|
|
|
1. **Ya incluido:** Permiso `unlimitedStorage` en manifest.json
|
|
|
|
2. **Verificar que está presente:**
|
|
```json
|
|
"permissions": [
|
|
"unlimitedStorage"
|
|
]
|
|
```
|
|
|
|
3. **Si sigue fallando:** Considerar:
|
|
- Comprimir la DB
|
|
- Usar chunks para storage
|
|
- Usar IndexedDB nativa
|
|
|
|
---
|
|
|
|
## Obtener Ayuda
|
|
|
|
Si ninguna solución funciona:
|
|
|
|
### 1. Recopilar información
|
|
|
|
**Información del sistema:**
|
|
- Navegador y versión: `about:support` (Firefox) o `chrome://version/` (Chrome)
|
|
- Versión de la extensión: Ver manifest.json
|
|
- Sistema operativo
|
|
|
|
**Logs:**
|
|
```javascript
|
|
// En consola del navegador (F12)
|
|
console.log("Extension ID:", browser.runtime.id);
|
|
console.log("Extension URL:", browser.runtime.getURL(""));
|
|
|
|
// En consola de background script
|
|
// (about:debugging > Inspeccionar)
|
|
// Copiar todos los console.log relevantes
|
|
```
|
|
|
|
**Errores:**
|
|
- Captura de pantalla de errores en consola
|
|
- Texto completo de mensajes de error
|
|
|
|
### 2. Verificar problemas conocidos
|
|
|
|
- GitHub Issues: https://github.com/JustOff/ca-archive/issues
|
|
- Buscar error específico
|
|
|
|
### 3. Reportar bug
|
|
|
|
Si no existe issue similar, crear uno nuevo:
|
|
|
|
**Plantilla:**
|
|
|
|
```markdown
|
|
## Descripción del problema
|
|
[Describe qué está fallando]
|
|
|
|
## Pasos para reproducir
|
|
1. [Primer paso]
|
|
2. [Segundo paso]
|
|
3. [...]
|
|
|
|
## Comportamiento esperado
|
|
[Qué debería pasar]
|
|
|
|
## Comportamiento actual
|
|
[Qué está pasando]
|
|
|
|
## Entorno
|
|
- Navegador: [Firefox 100 / Chrome 105]
|
|
- SO: [Linux / Windows / macOS]
|
|
- Versión extensión: [3.0.0]
|
|
|
|
## Logs
|
|
```
|
|
[Pegar logs de consola aquí]
|
|
```
|
|
|
|
## Capturas
|
|
[Adjuntar screenshots si aplica]
|
|
```
|
|
|
|
### 4. Contacto
|
|
|
|
- GitHub Issues: https://github.com/JustOff/ca-archive/issues
|
|
- Discusiones: https://github.com/JustOff/ca-archive/discussions
|
|
- Email: [Especificar si aplica]
|
|
|
|
---
|
|
|
|
## Debugging Avanzado
|
|
|
|
### Habilitar logging detallado
|
|
|
|
En `background.js`, agregar al inicio:
|
|
```javascript
|
|
const DEBUG = true;
|
|
|
|
function log(...args) {
|
|
if (DEBUG) console.log("[CA Archive]", ...args);
|
|
}
|
|
```
|
|
|
|
Luego usar `log()` en lugar de `console.log()`.
|
|
|
|
### Inspeccionar storage
|
|
|
|
```javascript
|
|
// Firefox
|
|
browser.storage.local.get(null).then(console.log);
|
|
|
|
// Chrome
|
|
chrome.storage.local.get(null, console.log);
|
|
```
|
|
|
|
### Ejecutar queries SQL manualmente
|
|
|
|
```javascript
|
|
// En consola de ca-archive.html
|
|
if (DB.db) {
|
|
const results = DB.execute("SELECT COUNT(*) FROM addons");
|
|
console.log(results);
|
|
}
|
|
```
|
|
|
|
### Profiling de rendimiento
|
|
|
|
1. Abrir DevTools (`F12`)
|
|
2. Ir a tab "Performance" / "Rendimiento"
|
|
3. Click en "Record" / "Grabar"
|
|
4. Realizar acción lenta
|
|
5. Stop y analizar flamegraph
|
|
|
|
---
|
|
|
|
## Recursos Adicionales
|
|
|
|
- [Documentación Mozilla WebExtensions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions)
|
|
- [Chrome Extensions API](https://developer.chrome.com/docs/extensions/reference/)
|
|
- [sql.js Documentation](https://sql.js.org/)
|
|
- [Debugging WebExtensions (Firefox)](https://extensionworkshop.com/documentation/develop/debugging/)
|
|
- [Debugging Chrome Extensions](https://developer.chrome.com/docs/extensions/mv2/tut_debugging/)
|
|
|
|
---
|
|
|
|
**¿Solucionaste tu problema?** ¡Considera contribuir esta solución a la documentación!
|
|
|
|
**¿Problema diferente?** Abre un issue en GitHub: https://github.com/JustOff/ca-archive/issues
|