Node.js-API (nodejs.org)
Fasst die Node.js-API-Dokumentation in dem zusammen, was ein Modell tendenziell falsch macht: unsichere Standardeinstellungen, Fallstricke, Deprecations. Jede Behauptung endet mit ihrer nodejs.org-Seite.
Abgedeckte Version
Die gelesene Dokumentation ist v26.13.0. Viele Projekte verwenden die v24-LTS-Linie, daher markieren die Referenzen, was neuer ist: „Hinzugefügt in v25.x“ oder „Hinzugefügt in v26.x“ bedeutet, dass es in v24 fehlt, sofern keine Backport-Version angegeben ist. https://nodejs.org/docs/latest/api/
Bevor Sie sich auf ein markiertes Feature verlassen, überprüfen Sie process.version oder führen Sie eine Feature-Erkennung durch (process.features.typescript, process.features.require_module). https://nodejs.org/docs/latest/api/process.html
Lesen Sie die folgenden Regeln und öffnen Sie dann die passende Referenzdatei.
Wichtigste Regeln
- Rufen Sie niemals
access(),exists()oderstat()vor dem Öffnen einer Datei auf: Öffnen Sie direkt und behandeln SieENOENT/EEXIST(Flag'wx'für exklusives Erstellen). https://nodejs.org/docs/latest/api/fs.html#fsaccesspath-mode-callback - Schließen Sie jedes
FileHandleexplizit, idealerweise mitawait using. EinFileHandle, das dem Garbage Collector überlassen bleibt, führt zu einem Fehler. https://nodejs.org/docs/latest/api/deprecations.html#DEP0137 - Komponieren Sie Streams mit
pipeline(), nicht mit.pipe()-Ketten, und beachten Sie, dasswrite()falsezurückgeben kann. https://nodejs.org/docs/latest/api/stream.html#readablepipedestination-options - Fügen Sie jedem Emitter, Stream, Socket, Request und Child Process einen
'error'-Listener hinzu: Ein unbehandelter'error'-Event stürzt den Prozess ab. https://nodejs.org/docs/latest/api/events.html#error-events - Verzweigen Sie auf Basis von
err.code, niemals auf Basis vonerr.message. https://nodejs.org/docs/latest/api/errors.html#errorcode - Setzen Sie
process.exitCodeanstelle vonprocess.exit(), da letzteres stdout abschneiden kann. https://nodejs.org/docs/latest/api/process.html#processexitcode - Setzen Sie die Arbeit nach
'uncaughtException'niemals fort: Räumen Sie synchron auf und beenden Sie den Prozess. https://nodejs.org/docs/latest/api/process.html#warning-using-uncaughtexception-correctly - Bevorzugen Sie
queueMicrotask()gegenüber dem veraltetenprocess.nextTick(). https://nodejs.org/docs/latest/api/process.html#when-to-use-queuemicrotask-vs-processnexttick - Verwenden Sie
execFile()/spawn()ohne Shell. Die Übergabe vonargsmitshell: trueescaped diese nicht. https://nodejs.org/docs/latest/api/deprecations.html#DEP0190 - Konsumieren Sie jeden HTTP-Client-Response-Body (
res.resume()mindestens), hängen Siereq.on('error')an, und denken Sie daran, dasstimeoutnicht abbricht: Rufen Siedestroy()auf. https://nodejs.org/docs/latest/api/http.html#class-httpclientrequest - Halten Sie
headersTimeoutauf Servern ohne Reverse Proxy ungleich Null. https://nodejs.org/docs/latest/api/http.html#serverheaderstimeout - Verwenden Sie die WHATWG-
URL.url.parse()ist veraltet und dafür werden keine CVEs mehr ausgestellt. https://nodejs.org/docs/latest/api/deprecations.html#DEP0169 path.isAbsolute()verhindert keinen Pfad-Traversal-Angriff, undpath.normalize()ist lexikalisch und kann ändern, wie das System den Pfad auflöst: Lösen Sie auf und überprüfen Sie dann, ob das Ergebnis innerhalb des Wurzelverzeichnisses bleibt. https://nodejs.org/docs/latest/api/path.html#pathisabsolutepath- Verwenden Sie standardmäßig
Buffer.alloc(), für AnsichtenBuffer.subarray()und niemalsnew Buffer(). https://nodejs.org/docs/latest/api/deprecations.html#DEP0005 - Vergleichen Sie Geheimnisse mit
crypto.timingSafeEqual()auf gleich langen Buffern. https://nodejs.org/docs/latest/api/crypto.html#cryptotimingsafeequala-b - Setzen Sie
maxOutputLengthbeim Dekomprimieren nicht vertrauenswürdiger Daten mit zlib (Standard istbuffer.kMaxLength). https://nodejs.org/docs/latest/api/zlib.html#class-options - Setzen Sie
"type"in derpackage.json, und setzen Sie"default"als letztes in den"exports"-Bedingungen. https://nodejs.org/docs/latest/api/packages.html#determining-module-system require()von ESM funktioniert für synchrone Graphen. Eintop-level awaitirgendwo im Graphen wirftERR_REQUIRE_ASYNC_MODULE. https://nodejs.org/docs/latest/api/modules.html#loading-ecmascript-modules-using-require- Type-Stripping führt
.tsohne Typprüfung aus: keinenum, explizite.ts-Erweiterungen,import typeund keinetsconfig-paths. Es ist stabil seit v25.2.0 (zurückportiert nach v24.12.0), erkennen Sie es mitprocess.features.typescript. https://nodejs.org/docs/latest/api/typescript.html#typescript-features , https://nodejs.org/docs/latest/api/typescript.html#type-stripping - Registrieren Sie Modul-Hooks mit
module.registerHooks().module.register()ist in v26 veraltet. https://nodejs.org/docs/latest/api/deprecations.html#DEP0205 - Bevorzugen Sie
AsyncLocalStoragegegenüberasync_hooks.createHook(). https://nodejs.org/docs/latest/api/async_hooks.html - Verwenden Sie
await t.test()für Subtests innode:test. https://nodejs.org/docs/latest/api/test.html#subtests node:vmund WASI sind keine Sandboxes, und das Berechtigungsmodell ist kein sicherer Weg, um nicht vertrauenswürdigen Code auszuführen: Verwenden Sie sie niemals dafür. https://nodejs.org/docs/latest/api/permissions.html#process-based-permissions- Entsorgen Sie Server, Streams und Child Processes mit
using/await usingund nicht mit einemAbortSignal. Behalten Sie Signale für Abbruch und Timeouts. https://nodejs.org/docs/latest/api/deprecations.html#DEP0209 dns.lookup()istgetaddrinfoim Thread-Pool, keine DNS-Abfrage. https://nodejs.org/docs/latest/api/dns.html#implementation-considerations- Dimensionieren Sie Pools mit
os.availableParallelism(). https://nodejs.org/docs/latest/api/os.html#osavailableparallelism node:sqlite: Binden Sie Parameter, interpolieren Sie niemals in SQL. https://nodejs.org/docs/latest/api/sqlite.html#binding-parameters- Führen Sie CI mit
--pending-deprecationaus, um Deprecations sichtbar zu machen. https://nodejs.org/docs/latest/api/deprecations.html
Referenzdateien
| Datei | Lesen für |
|---|---|
| references/fs.md | TOCTOU, FileHandle, readFile/writeFile, rm, glob, fs.watch |
| references/path-and-url.md | path, Traversal, file:-URLs, WHATWG-URL, querystring |
| references/crypto.md | KeyObject, timingSafeEqual, Hashing, pbkdf2, scrypt, schwache Algorithmen |
| references/ciphers-and-webcrypto.md | AEAD-Tags, GCM, Key Wrap, subtle, Schlüsselformate |
| references/streams.md | pipeline, Backpressure, highWaterMark, finished, Implementierung von Streams |
| references/web-streams-and-stream-iter.md | Web Streams, node:stream/iter |
| references/buffer.md | alloc versus allocUnsafe, Kodierungen, Blob |
| references/zlib.md | Dekompressionsbomben, Flush, Zstd |
| references/http-client.md | http.request, Agents, Keep-Alive, Proxy |
| references/http-server.md | Timeouts, Graceful Shutdown, HTTPS-Server |
| references/net-dns-dgram.md | TCP, BlockList, dns.lookup versus resolve, UDP |
| references/tls.md | SNI, Ciphers, CA-Store, Session Resumption |
| references/http2.md | Sicherer Server, allowHTTP1, Härtung |
| references/process.md | Exit-Codes, Signale, uncaughtException, Zurückweisungen |
| references/cli-and-env-files.md | NODE_OPTIONS, --env-file, --watch |
| references/permissions.md | --permission, bekannte Lücken |
| references/errors.md | error.code, cause, Fehlercodes |
| references/events-and-timers.md | captureRejections, events.once, EventTarget, Timer |
| references/async-context-and-diagnostics-channel.md | AsyncLocalStorage, diagnostics_channel |
| references/util-and-console.md | util, Console |
| references/os-tty-readline-repl.md | os, tty, readline, REPL |
| references/test-runner.md | Subtests, Isolation, Coverage, Reporter, Mocks |
| references/assert-and-bench.md | node:assert/strict, tiefe Gleichheit, node:bench |
| references/esm-and-commonjs.md | "type", JSON-Importe, import.meta, require(esm) |
| references/packages.md | "exports", "imports", Bedingungen, Dual Packages |
| references/typescript-and-module-hooks.md | Type-Stripping, registerHooks, findPackageJSON |
| references/globals.md | fetch, AbortSignal, Globals |
| references/child-process.md | execFile versus exec, maxBuffer, IPC |
| references/worker-threads-and-cluster.md | Pools, Transferlisten, Cluster |
| references/vm-wasi-vfs.md | vm, WASI, node:vfs |
| references/performance-and-profiling.md | perf_hooks, Heap-Snapshots |
| references/debugging-and-reports.md | Inspector, Diagnoseberichte |
| references/sqlite.md | Database, Standardwerte, Bindung, Typkonvertierung |
| references/sea-and-native.md | SEA, Node-API-Regeln, node:ffi |
| references/deprecations.md | DEP-Codes, entfernte APIs, Codemods |
Gelesene Seiten, Version und Abrufdatum sind in SOURCES.md aufgelistet.