Error fatal a WooCommerce: guia pràctica per resoldre’l

Símptomes

• Hi ha hagut un error crític en aquest lloc web a la botiga, les fitxes de producte, el checkout o l’administració.
• Una pantalla en blanc o una resposta HTTP 500.
• Un checkout que no para de carregar perquè la seva petició falla amb un 500.
• Un correu a l’administrador amb l’assumpte El vostre lloc web té un problema tècnic.

Causes més habituals

Diagnosi

1. Aconsegueix l’error complet

Per ordre de comoditat:

1. El correu que WordPress envia a l’administrador quan captura un error fatal.
2. WooCommerce → Estat → Registres, origen fatal-errors.
3. El registre d’errors PHP del tauler del hosting.
4. wp-content/debug.log, després d’activar el registre:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );      // o una ruta fora de l’arrel web
define( 'WP_DEBUG_DISPLAY', false ); // no mostris mai errors als clients
@ini_set( 'display_errors', '0' );

2. Llegeix-lo en quatre parts

PHP Fatal error:  Uncaught TypeError: Unsupported operand types: string + float
  in /var/www/wp-content/plugins/custom-fees/custom-fees.php:142
Stack trace:
#0 /var/www/wp-includes/class-wp-hook.php(324): add_custom_fee(Object(WC_Cart))
#1 /var/www/wp-includes/plugin.php(205): WP_Hook->apply_filters(...)
#2 /var/www/wp-content/plugins/woocommerce/includes/class-wc-cart.php(...): do_action('woocommerce_cart_calculate_fees', ...)

• Tipus i missatge: un TypeError, és a dir, tipus incorrectes, no un fitxer que falta.
• Fitxer i línia: custom-fees.php:142, un plugin a mida, no WooCommerce.
• Traça: WooCommerce hi ha arribat mentre calculava els càrrecs del carretó.
• Hora (al prefix de la línia del registre): relaciona-la amb l’última actualització, desplegament o canvi de PHP.

3. Relaciona’l amb un canvi

Mira què va canviar just abans de la primera aparició: actualitzacions de plugins i del tema, un snippet nou, un canvi de versió de PHP, una actualització de WooCommerce que va canviar el que passa un hook. La majoria d’errors fatals són la primera execució d’un camí de codi nou després d’un canvi.

Registres i comprovacions tècniques

• Registre fatal-errors, registre d’errors PHP, debug.log.
• WooCommerce → Estat → Estat del sistema: versió de PHP, límit de memòria, versions de WooCommerce i de les extensions.
• El changelog del plugin per a la versió instal·lada just abans que aparegués l’error.
• Per a errors de memòria: quina petició, amb quina freqüència i què estava carregant.

Solucions

• Reverteix el component que va introduir l’error a la versió anterior, com a mesura provisional, mentre es prepara la correcció real.
• Arregla el codi de manera defensiva: comprova els valors retornats, converteix els tipus i gestiona comandes o productes inexistents.
• Actualitza els plugins incompatibles amb les versions actuals de PHP i WooCommerce, o substitueix els abandonats.
• Elimina duplicats: el mateix snippet en un plugin de snippets i a functions.php, o dos plugins que inclouen llibreries en conflicte.
• Per als límits de temps i memòria, arregla el que és lent o pesat; apuja els límits només per a tasques pesades legítimes, idealment en segon pla.

// Abans: error fatal quan get_option() retorna un text
$fee = $cart->get_subtotal() * get_option( 'handling_rate' );

// Després: tipus explícits, i res a afegir si la taxa no està configurada
$rate = (float) get_option( 'handling_rate', 0 );
if ( $rate > 0 ) {
    $cart->add_fee( __( 'Despeses de gestió', 'my-store' ), $cart->get_subtotal() * $rate );
}

Què no s’ha de fer

• No activis la visualització d’errors en una botiga en producció; registra’ls.
• No editis els fitxers d’un plugin de tercers a producció. El canvi es perd amb la següent actualització i ningú no sap que existeix.
• No reinstal·lis WooCommerce ni restauris una còpia antiga sense conèixer la causa: pots perdre comandes i quedar-te amb l’error.
• No esborris el registre després de llegir-lo; el necessitaràs per confirmar la correcció.

Quan recórrer a un expert

Recorre a un enginyer quan l’error és dins de codi a mida o d’una extensió prèmium que no pots canviar amb seguretat, quan és intermitent, quan va aparèixer en molts fitxers després d’actualitzar PHP, o quan bloqueja el checkout o l’administració ara mateix.

Problemes relacionats

• WooCommerce / Errors Conflicte de plugins a WooCommerce: com trobar la causa Parteix de les evidències (l’error, el moment, la petició) i aïlla a staging per meitats, no plugin a plugin a producció. →
• WooCommerce / Checkout El checkout de WooCommerce no funciona: com diagnosticar la causa arrel Determina primer si la fallada passa abans de la petició del checkout, durant la petició o després de la resposta de la passarel·la. El panell de xarxa i els registres PHP solen mostrar quina capa falla. →
• WooCommerce / HPOS HPOS a WooCommerce: problemes habituals amb codi personalitzat Consultes directes a wp_posts, get_post_meta() sobre comandes i altre codi que falla en silenci quan les comandes passen a les seves pròpies taules. →

Preguntes freqüents