Busca en todas las páginas de la documentación
Cuando el comportamiento de Node.js te sorprende, la referencia oficial de la API y las banderas de diagnóstico integradas superan las respuestas de Stack Overflow de versiones principales desactualizadas.
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
node --help # Banderas CLI
node -p "process.versions" # versiones exactas en este binario
NODE_DEBUG=module node app.mjs # rastrear la carga de módulos
node --trace-warnings app.mjs # mostrar rastreos de pila de advertencias
node --report-on-fatalerror app.mjs # escribir informe de diagnóstico en caso de falloCuándo recurrir a esto:
exports o imports// diagnostics.ts - habilita advertencias útiles en desarrollo
import { emitWarning } from 'node:process';
if (process.env.NODE_ENV !== 'production') {
// Muestra advertencias de obsolescencia con pilas
process.on('warning', (w) => {
console.warn('[node-warning]', w.name, w.message);
if (w.stack) console.warn(w.stack);
});
}
export function writeDiagnosticReport(reason: string): string {
const report = process.report?.writeReport(reason);
return report ?? 'report-unavailable';
}# Ejecutar con banderas de rastreo durante la reproducción local
NODE_OPTIONS="--trace-warnings --trace-deprecation" node --import tsx src/main.ts
# Confusión en la resolución de módulos
NODE_DEBUG=esm node src/main.ts 2>&1 | head -40Lo que esto demuestra:
process.on('warning') captura las obsolescencias antes de que se conviertan en fallos gravesNODE_OPTIONS centraliza las banderas en scripts npm y contenedoresNODE_DEBUG=esm registra las decisiones del cargador ESM, invaluable para errores de campo exportsprocess.report.writeReport() produce JSON para análisis post-mortemnodejs.org/api está versionada; selecciona v24.18.0 para que coincida con tu entorno de ejecución.--report-on-fatalerror, SIGUSR2) capturan el heap, la pila, los manejadores de libuv y el entorno.NODE_DEBUG=http, net, module, esm).nodejs/node CHANGELOG) documentan los cambios importantes por versión menor/parche.| Síntoma | Primer recurso | Bandera / herramienta |
|---|---|---|
| Módulo no encontrado | Documentos node:module, exports de package.json | NODE_DEBUG=module |
| Advertencia de obsolescencia | Notas de la versión para tu versión objetivo | --trace-deprecation |
| Crecimiento de memoria | memoryUsage de node:process | --heapsnapshot-near-heap-limit=3 |
| Retraso del bucle de eventos | Documentos del bucle de eventos | monitorEventLoopDelay |
| Peculiaridades HTTP | Documentos node:http | NODE_DEBUG=http |
import { styleText } from 'node:util';
// Node 24 util.styleText para una salida de diagnóstico CLI legible
console.log(styleText('yellow', 'Advertencia:'), 'Consulta nodejs.org/api/v24 para cambios en la API');nodejs.org/api/v24.x.--trace-deprecation en CI.nodejs/node y en el CHANGELOG.NODE_DEBUG en producción: los registros detallados filtran los internos y cuestan E/S. Solución: reproduce localmente con depuración, usa registro estructurado en producción.engines cuando la documentación asume una versión: los ejemplos pueden usar APIs ausentes en tu entorno de ejecución. Solución: alinea local, CI y producción en 24.18.0.| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
| MDN (para APIs web) | fetch, URL, TextEncoder | Módulos específicos de Node como node:fs |
| README del paquete | Comportamiento específico de la biblioteca | Semántica del tiempo de ejecución del núcleo |
node --experimental-print-required-tla | Errores de ordenación de await de nivel superior | Depuración HTTP general |
| APM / OpenTelemetry | Distribuciones de latencia de producción | Comprender una única firma de API |
Visita https://nodejs.org/docs/latest-v24.x/api/index.html o ejecuta node -p "process.version" y haz coincidir la versión principal en el selector de versiones.
Una variable de entorno que habilita el rastreo interno de Node. Valores comunes: module, esm, http, net. La salida va a stderr.
Ejecuta con node --trace-warnings o establece NODE_OPTIONS=--trace-warnings.
Un archivo JSON con una instantánea de la pila, el heap, los manejadores de uv y el entorno. Se activa en errores fatales o mediante SIGUSR2 cuando está configurado.
En el CHANGELOG de Node.js en GitHub y en las publicaciones de blog de lanzamiento para cada versión principal. Busca "Semver-Major".
NODE_DEBUG=esm muestra las decisiones de importación. También lee package.json exports.
Busca primero los problemas. Abre un nuevo problema con la versión de reproducción (node -v), la plataforma y un script de reproducción mínimo.
Trata las obsolescencias pendientes como advertencias activas, útil al prepararse para la próxima actualización principal.
Ejecuta el mismo script en ambas versiones con fnm exec 22.23.1 -- node script.mjs y fnm exec 24.18.0 -- node script.mjs.
node:fetch está documentado en las APIs compatibles con la web. MDN cubre la forma de la API; la documentación de Node cubre las opciones específicas de Node.
import { writeHeapSnapshot } from 'node:v8';
writeHeapSnapshot(`./heap-${Date.now()}.heapsnapshot`);https://nodejs.org/en/blog/vulnerability y la lista de correo nodejs-sec.
Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.
Revisado por Chris St. John·Última actualización: 16 jul 2026