← Cloudflare Workers / workers / runtime-apis
Совместимость с Node.js
При написании Worker может понадобиться импортировать пакеты из npm ↗. Многие npm-пакеты полагаются на API из среда выполнения Node.js ↗, и не будет работать, если эти API Node.js недоступны.
Cloudflare Workers предоставляет подмножество Node.js API в двух формах:
- Как встроенные API, предоставляемые Workers Runtime. Большинство из этих API являются полными реализациями соответствующих API Node.js, тогда как некоторые поддерживаются частично.
- Поскольку реализации полифил-шима, которые Wrangler добавляет в код вашего Worker, позволяя ему импортировать модуль, но вызов методов API будет приводить к ошибкам.
Начало работы
Для дат совместимости 2026-08-04 или более поздней версии Workers включает оба nodejs_compat и nodejs_compat_v2 по умолчанию. Встроенные API и полифиллы Node.js доступны без дополнительной настройки.
Для этих дат совместимости nodejs_compat и nodejs_compat_v2 не используются, потому что compatibility date включает такое же поведение. Существующим проектам не нужно удалять эти флаги при обновлении compatibility date. В новых конфигурациях их не указывайте.
Для дат совместимости начиная с 2024-09-23 через 2026-08-03, добавьте nodejs_compat флаг совместимости в конфигурационный файл Wrangler чтобы включить:
{
"compatibility_date": "2026-08-03",
"compatibility_flags": ["nodejs_compat"]
}compatibility_date = "2026-08-03"
compatibility_flags = [ "nodejs_compat" ]Чтобы полностью отключить совместимость с Node.js с датой совместимости 2026-08-04 или более поздней версии удалите положительные флаги, если они есть. Затем добавьте оба no_nodejs_compat и no_nodejs_compat_v2. Примеры настройки см. в Флаг совместимости с Node.js.
Поддерживаемые API Node.js
API среды выполнения Node.js, перечисленные в этом разделе со статусом "🟢 supported", в настоящее время нативно поддерживаются в Workers Runtime. Элементы со статусом "🟡 partially supported" включают API, пригодные для использования, но не реализующие полностью поверхность API Node.js.
Устаревшие или экспериментальные API Node.js ↗, а API, которые не подходят для бессерверного контекста, не включены в список поддерживаемых API в этом разделе. Некоторые заглушки только для импорта для таких API перечислены отдельно в Нефункциональные модули-заглушки.
| Имя API | Изначально поддерживается Workers Runtime |
|---|---|
| Тестирование с помощью утверждений | 🟢 поддерживается |
| Отслеживание асинхронного контекста | 🟢 поддерживается |
| Buffer | 🟢 поддерживается |
| Консоль ↗ | 🟡 частично поддерживается |
| Crypto | 🟢 поддерживается |
| Отладчик | 🟢 поддерживается через Интеграция с Chrome DevTools |
| Diagnostics Channel | 🟢 поддерживается |
| DNS | 🟡 частично поддерживается |
| Ошибки | 🟢 поддерживается |
| События | 🟢 поддерживается |
| Файловая система | 🟢 поддерживается |
| Глобальные объекты | 🟢 поддерживается |
| HTTP | 🟢 поддерживается |
| HTTPS | 🟢 поддерживается |
| Модуль ↗ | 🟡 частично поддерживается |
| Нетто | 🟢 поддерживается |
| ОС ↗ | 🟡 частично поддерживается |
| Путь | 🟢 поддерживается |
| Хуки производительности ↗ | 🟡 частично поддерживается |
| Процесс | 🟢 поддерживается |
| Punycode ↗ (устарело) | 🟢 поддерживается |
| Строки запроса ↗ | 🟢 поддерживается |
| Stream | 🟢 поддерживается |
| Декодер строк | 🟢 поддерживается |
| Средство запуска тестов | 🟡 частично поддерживается |
| Таймеры | 🟢 поддерживается |
| TLS/SSL | 🟡 частично поддерживается |
| URL | 🟢 поддерживается |
| Утилиты | 🟢 поддерживается |
| Web Crypto API | 🟢 поддерживается |
| Web Streams API | 🟢 поддерживается |
| Zlib | 🟢 поддерживается |
Если не указано иное, встроенные реализации API Node.js в Workers должны соответствовать реализации в Текущий релиз Node.js ↗.
Если API, который вы хотите использовать, отсутствует, и вы хотите предложить добавить его поддержку в Workers, оставьте сообщение или комментарий в Категория обсуждений API Node.js ↗ на GitHub.
Нефункциональные модули-заглушки
Некоторые модули Node.js доступны в виде нерабочих заглушек. Такую заглушку можно импортировать или подключить через require, но она не содержит рабочей реализации соответствующего API Node.js. Заглушки нужны для того, чтобы пакеты, которые лишь проверяют наличие модуля, могли загружаться в Workers, но использовать их напрямую в коде приложения не следует.
Следующие stubs включаются автоматически, только если nodejs_compat флаг совместимости включён и дата совместимости Worker наступает не раньше указанной. Чтобы включить функцию раньше, добавьте соответствующий флаг включения. Чтобы она оставалась недоступной и после этой даты, добавьте соответствующий флаг отключения.
| Заглушка модуля | Включено с nodejs_compat начиная с указанной даты |
Включить флаг | Отключить флаг |
|---|---|---|---|
node:http2 ↗ |
2025-09-01 |
enable_nodejs_http2_module |
disable_nodejs_http2_module |
node:vm ↗ |
2025-10-01 |
enable_nodejs_vm_module |
disable_nodejs_vm_module |
node:cluster ↗ |
2025-12-04 |
enable_nodejs_cluster_module |
disable_nodejs_cluster_module |
node:domain ↗ |
2025-12-04 |
enable_nodejs_domain_module |
disable_nodejs_domain_module |
node:trace_events ↗ |
2025-12-04 |
enable_nodejs_trace_events_module |
disable_nodejs_trace_events_module |
node:wasi ↗ |
2025-12-04 |
enable_nodejs_wasi_module |
disable_nodejs_wasi_module |
node:_stream_wrap |
2026-01-29 |
enable_nodejs_stream_wrap_module |
disable_nodejs_stream_wrap_module |
node:dgram ↗ |
2026-01-29 |
enable_nodejs_dgram_module |
disable_nodejs_dgram_module |
node:inspector ↗ |
2026-01-29 |
enable_nodejs_inspector_module |
disable_nodejs_inspector_module |
node:sqlite ↗ |
2026-01-29 |
enable_nodejs_sqlite_module |
disable_nodejs_sqlite_module |
node:child_process ↗ |
2026-03-17 |
enable_nodejs_child_process_module |
disable_nodejs_child_process_module |
node:readline ↗ |
2026-03-17 |
enable_nodejs_readline_module |
disable_nodejs_readline_module |
node:repl ↗ |
2026-03-17 |
enable_nodejs_repl_module |
disable_nodejs_repl_module |
node:tty ↗ |
2026-03-17 |
enable_nodejs_tty_module |
disable_nodejs_tty_module |
node:v8 ↗ |
2026-03-17 |
enable_nodejs_v8_module |
disable_nodejs_v8_module |
node:worker_threads ↗ |
2026-03-17 |
enable_nodejs_worker_threads_module |
disable_nodejs_worker_threads_module |
Полифилы API Node.js
API Node.js, которые пока не поддерживаются в среде выполнения Workers, реализуются через полифилы с помощью Wrangler, который использует unenv ↗. Если nodejs_compat флаг совместимости включен, а у вашего Worker дата совместимости от 2024-09-23 или более поздняя, Wrangler автоматически добавит полифилы в код вашего Worker.
Полифиллы максимально повышают совместимость с существующими npm-пакетами за счет модулей с заглушенными методами. Вызов таких методов либо не даст эффекта, либо вызовет ошибку с сообщением вида:
[unenv] <method name> is not implemented yet!Это позволяет импортировать пакеты, использующие эти модули Node.js, даже если некоторые методы не поддерживаются.
Включить только AsyncLocalStorage
Если вам нужно включить только Node.js AsyncLocalStorage API можно включить nodejs_als флаг совместимости:
{
"compatibility_flags": ["nodejs_als"],
}compatibility_flags = [ "nodejs_als" ]