Error Node.js 0308010C: Soluciones de verdad (y por qué no usar hacks)

Si estás lidiando con el mensaje error:0308010C:digital envelope routines::unsupported, créeme, no eres el único. Este error empezó a aparecer con Node.js v17 y, de hecho, se hizo más común cuando Node 18 se convirtió en LTS, debido al cambio a OpenSSL 3.0.

La razón es simple: Node.js, desde su versión 17, adoptó OpenSSL 3.0, que es más estricto con la seguridad. Muchas dependencias antiguas de tu proyecto, que confían en versiones obsoletas de SSL, simplemente dejan de funcionar. Es un cambio importante y, en mi opinión, necesario para la seguridad.

El "arreglo" rápido que NO te recomiendo

Lo primero que muchos encuentran, y que yo mismo he visto proponer en discusiones de arquitectura, es la siguiente variable de entorno:

export NODE_OPTIONS=--openssl-legacy-provider

Esta línea fuerza a Node.js a usar el proveedor OpenSSL antiguo, menos seguro. Sí, hace que tu código compile y funcione al instante. Pero ojo que esto no soluciona el problema de raíz, solo lo esconde. Estás bajando la seguridad de tu entorno de ejecución, abriendo puertas a posibles vulnerabilidades. En mi caso, jamás lo usaría en producción.

Las soluciones que sí valen la pena

La solución correcta siempre pasa por actualizar. Si tus dependencias no son compatibles con OpenSSL 3.0, el problema está en ellas, no en Node.js.

1. Actualiza tus dependencias

Esta es la vía principal. Intenta una actualización general de paquetes:

npm update
npm audit fix --force

El comando npm audit fix --force intentará resolver los problemas de seguridad automáticamente, aunque a veces puede traer cambios importantes. Para usuarios de Yarn, la herramienta yarn-audit-fix hace algo similar.

Si esto no basta, investiga qué dependencia es la problemática. A menudo, son herramientas de build como Webpack o sus plugins los que causan el conflicto. Identifícala y actualízala a una versión compatible con Node 18+.

2. Configuración específica de Webpack (si es tu caso)

Si el error persiste y usas Webpack, a veces la solución está en su configuración. Puedes cambiar el algoritmo de hash que usa. Para Webpack v5, por ejemplo:

module.exports = {
  // ... otras configuraciones
  output: {
    // ...
    hashFunction: 'xxhash64',
  },
};

Esto a mí me parece una solución más de nicho, que ataca el síntoma en un componente específico, pero puede ser útil si todo lo demás falla y tienes claro que Webpack es el culpable.

Mi experiencia y lo que haría diferente

Recuerdo un proyecto de un cliente donde este error nos pilló a las 2 AM. El equipo de Ops quería meter el NODE_OPTIONS a la fuerza en el CI/CD para salir del paso. Insistí en que no era la forma. Nos costó dos horas de debugging y actualizar una pila de dependencias viejas de Webpack, pero al final, el pipeline pasó limpio y seguro. No soy fan de los parches que esconden la mugre.

Si tuviera que empezar de cero un proyecto hoy, desde el día uno, me aseguraría de integrar herramientas como npm-check-updates o incluso algo como Dependabot en GitHub. Mantener las dependencias al día es una inversión que evita dolores de cabeza como este, y que te ahorra horas de debugging de madrugada. No hay atajos para la seguridad y la estabilidad, eso lo aprendí a palos.