544
TROUBLESHOOTING.md
Archivo normal
544
TROUBLESHOOTING.md
Archivo normal
@@ -0,0 +1,544 @@
|
||||
# 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
|
||||
Referencia en una nueva incidencia
Block a user