Lendo a Documentação Oficial e Diagnósticos
Quando o comportamento do Node.js surpreende você, a referência oficial da API e as flags de diagnóstico integradas superam as respostas do Stack Overflow de versões principais desatualizadas.
//
Busque em todas as páginas da documentação
Quando o comportamento do Node.js surpreende você, a referência oficial da API e as flags de diagnóstico integradas superam as respostas do Stack Overflow de versões principais desatualizadas.
Cartão de receita de referência rápida - pronto para copiar e colar.
node --help # Flags da CLI
node -p "process.versions" # versões exatas neste binário
NODE_DEBUG=module node app.mjs # rastrear carregamento de módulo
node --trace-warnings app.mjs # mostrar rastros de pilha de avisos
node --report-on-fatalerror app.mjs # escrever relatório de diagnóstico em caso de falhaQuando usar isso:
exports ou imports// diagnostics.ts - habilita avisos úteis em desenvolvimento
import { emitWarning } from 'node:process';
if (process.env.NODE_ENV !== 'production') {
// Expõe avisos de depreciação com pilhas de chamada
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';
}# Executar com flags de rastreamento durante a reprodução local
NODE_OPTIONS="--trace-warnings --trace-deprecation" node --import tsx src/main.ts
# Confusão na resolução de módulos
NODE_DEBUG=esm node src/main.ts 2>&1 | head -40O que isso demonstra:
process.on('warning') captura depreciações antes que se tornem falhas gravesNODE_OPTIONS centraliza flags em scripts npm e contêineresNODE_DEBUG=esm registra decisões do carregador ESM - inestimável para bugs no campo exportsprocess.report.writeReport() produz JSON para análises pós-incidentenodejs.org/api é versionada - selecione v24.18.0 para corresponder ao seu runtime.--report-on-fatalerror, SIGUSR2) capturam heap, pilha, handles libuv e ambiente.NODE_DEBUG=http, net, module, esm).nodejs/node CHANGELOG) documentam mudanças drásticas por versão secundária/correção.| Sintoma | Primeiro recurso | Flag / ferramenta |
|---|---|---|
| Módulo não encontrado | Documentação node:module, package.json exports | NODE_DEBUG=module |
| Aviso de depreciação | Notas de lançamento para sua versão alvo | --trace-deprecation |
| Crescimento de memória | node:process memoryUsage | --heapsnapshot-near-heap-limit=3 |
| Atraso no loop de eventos | Documentação do Event Loop | monitorEventLoopDelay |
| Estranhezas HTTP | Documentação node:http | NODE_DEBUG=http |
import { styleText } from 'node:util';
// Node 24 util.styleText para saída de diagnóstico CLI legível
console.log(styleText('yellow', 'Aviso:'), 'Verifique nodejs.org/api/v24 para mudanças na API');nodejs.org/api/v24.x.--trace-deprecation em CI.nodejs/node.NODE_DEBUG em produção - logs verbosos vazam detalhes internos e custam I/O. Correção: reproduza localmente com debug, use logging estruturado em produção.engines quando a documentação assume uma versão - exemplos podem usar APIs ausentes no seu runtime. Correção: alinhe local, CI e produção em 24.18.0.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| MDN (para APIs Web) | fetch, URL, TextEncoder | Módulos específicos do Node como node:fs |
| README do Pacote | Comportamento específico da biblioteca | Semântica do runtime principal |
node --experimental-print-required-tla | Bugs de ordenação de top-level await | Depuração HTTP geral |
| APM / OpenTelemetry | Distribuições de latência de produção | Entender uma única assinatura de API |
Visite https://nodejs.org/docs/latest-v24.x/api/index.html ou execute node -p "process.version" e combine a versão principal no seletor de versão.
Uma variável de ambiente que habilita o rastreamento interno do Node. Valores comuns: module, esm, http, net. A saída vai para stderr.
Execute com node --trace-warnings ou defina NODE_OPTIONS=--trace-warnings.
Um arquivo JSON com snapshot de pilha, heap, handles uv e ambiente. Acionado em erros fatais ou via SIGUSR2 quando configurado.
No CHANGELOG do Node.js no GitHub e em posts de blog de lançamento para cada versão principal. Procure por "Semver-Major".
NODE_DEBUG=esm mostra as decisões de importação. Leia também package.json exports.
Pesquise primeiro nos issues. Abra um novo issue com a versão de reprodução (node -v), plataforma e um script de reprodução mínimo.
Trata depreciações pendentes como avisos ativos - útil ao se preparar para a próxima atualização principal.
Execute o mesmo script em ambas as versões com fnm exec 22.23.1 -- node script.mjs e fnm exec 24.18.0 -- node script.mjs.
node:fetch é documentado em APIs compatíveis com a Web. O MDN cobre a forma da API; a documentação do Node cobre opções específicas do Node.
import { writeHeapSnapshot } from 'node:v8';
writeHeapSnapshot(`./heap-${Date.now()}.heapsnapshot`);https://nodejs.org/en/blog/vulnerability e a lista de emails nodejs-sec.
Versões da Pilha: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026