← Cloudflare Workers / workers / runtime-apis

Kompatibilita s Node.js

Při psaní Workeru možná budete potřebovat importovat balíčky z npm ↗. Mnoho npm balíčků se spoléhá na API z Runtime Node.js ↗, a nebude fungovat, pokud nejsou dostupná tato Node.js API.

Cloudflare Workers poskytuje podmnožinu Node.js API ve dvou formách:

1. Jako vestavěná API poskytovaná Workers Runtime. Většina těchto API je plnou implementací odpovídajících API v Node.js, zatímco několik z nich je podporováno jen částečně.
2. Jako implementace polyfill shimů, které Wrangler přidává do kódu vašeho Workeru, což mu umožňuje modul importovat, ale volání metod API vyvolá chyby.

Pro data kompatibility 2026-08-04 nebo novější Workers povolí oba nodejs_compat a nodejs_compat_v2 ve výchozím nastavení. Vestavěná Node.js API a polyfilly jsou dostupné bez dalšího nastavení.

Pro tato data kompatibility nodejs_compat a nodejs_compat_v2 se nepoužívají, protože stejné chování zajišťuje datum kompatibility. Stávající projekty tyto příznaky při aktualizaci data kompatibility odstraňovat nemusí. V nových konfiguracích je vynechte.

Pro data kompatibility od 2024-09-23 přes 2026-08-03, přidejte nodejs_compat příznak kompatibility do Konfigurační soubor Wrangler abyste se přihlásili:

{
	"compatibility_date": "2026-08-03",
	"compatibility_flags": ["nodejs_compat"]
}

compatibility_date = "2026-08-03"
compatibility_flags = [ "nodejs_compat" ]

Chcete-li úplně vypnout kompatibilitu s Node.js s datem kompatibility 2026-08-04 nebo novější odeberte pozitivní příznaky, pokud jsou přítomné. Poté přidejte oba no_nodejs_compat a no_nodejs_compat_v2. Příklady konfigurace najdete v Příznak kompatibility s Node.js.

Runtime API z Node.js uvedená v této části se stavem "🟢 supported" jsou v Workers Runtime aktuálně nativně podporována. Položky se stavem "🟡 partially supported" zahrnují použitelná API, ale neimplementují celý povrch API Node.js.

Zastaralá nebo experimentální rozhraní API z Node.js ↗, a rozhraní API, která se nehodí do bezserverového kontextu, nejsou zahrnuta v seznamu podporovaných API v této části. Některé pouze importovatelné náhrady pro tato API jsou uvedeny samostatně v Nefunkční stub moduly.

Pokud není uvedeno jinak, nativní implementace Node.js API ve Workers mají odpovídat implementaci v Aktuální verze Node.js ↗.

Pokud vám v nabídce chybí API, které chcete použít, a chtěli byste navrhnout, aby jej Workers podporovaly, přidejte příspěvek nebo komentář na Kategorie diskuzí k Node.js API ↗ na GitHubu.

Některé moduly Node.js jsou dostupné jen jako nefunkční stuby. Stub lze importovat nebo require, ale neposkytuje funkční implementaci odpovídajícího Node.js API. Tyto stuby existují proto, aby se v prostředí Workers daly načíst balíčky, které kontrolují přítomnost modulu, pro přímé použití v kódu aplikace ale vhodné nejsou.

Následující stuby se automaticky povolí pouze v případě, že nodejs_compat příznak kompatibility je povolen a datum kompatibility Workeru je na zobrazeném datu nebo po něm. Chcete-li chování povolit dříve, přidejte odpovídající povolovací příznak. Chcete-li ho po tomto datu ponechat nedostupné, přidejte odpovídající zakazovací příznak.

Rozhraní Node.js API, která zatím nejsou podporována v runtime Workers, jsou polyfillována pomocí Wrangler, který používá unenv ↗. Pokud nodejs_compat příznak kompatibility je povoleno a vašeho Workeru compatibility date je 2024-09-23 nebo novější, Wrangler automaticky vloží polyfilly do kódu vašeho Workeru.

Přidání polyfillů maximalizuje kompatibilitu se stávajícími balíčky npm tím, že poskytuje moduly s mockovanými metodami. Volání těchto mockovaných metod buď neudělá nic (noop), nebo vyvolá chybu se zprávou podobnou této:

[unenv] <method name> is not implemented yet!

To vám umožňuje importovat balíčky, které tyto moduly Node.js používají, i když některé metody nejsou podporovány.

Pokud potřebujete povolit pouze Node.js AsyncLocalStorage API můžete povolit nodejs_als příznak kompatibility:

{
	"compatibility_flags": ["nodejs_als"],
}

compatibility_flags = [ "nodejs_als" ]