njs: Модули NGINX njs

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

RedHat Enterprise Linux 7, 8, 9 и 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 и Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-njs

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-njs

Включите модуль, добавив следующее в верхнюю часть файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_js_module.so;

load_module modules/ngx_stream_js_module.so;

Этот документ описывает nginx-module-njs v0.9.6, выпущенный 3 марта 2026 года.

Баннер NGINX JavaScript

NGINX JavaScript

NGINX JavaScript, также известный как NJS, является динамическим модулем для NGINX, который позволяет расширять встроенную функциональность с использованием знакомого синтаксиса JavaScript. Язык NJS является подмножеством JavaScript, совместимым с ES5 (ECMAScript 5.1 Строгий вариант) с некоторыми расширениями ES6 (ECMAScript 6) и новее. См. совместимость для получения дополнительных сведений.

Как это работает

NGINX JavaScript предоставляется в виде двух динамических модулей для NGINX (ngx_http_js_module и ngx_stream_js_module) и может быть добавлен в любую поддерживаемую установку NGINX Open Source или NGINX Plus без повторной компиляции.

Модуль NJS позволяет администраторам NGINX: - Добавлять сложные проверки контроля доступа и безопасности перед тем, как запросы достигнут upstream-серверов - Манипулировать заголовками ответов - Писать гибкие, асинхронные обработчики контента, фильтры и многое другое!

Смотрите примеры и наши различные проекты, разработанные с использованием NJS:

https://github.com/nginxinc/nginx-openid-connect

Расширяет функциональность NGINX Plus для прямого взаимодействия с совместимыми с OIDC поставщиками удостоверений, аутентифицируя пользователей и авторизуя контент, доставляемый NGINX Plus.

https://github.com/nginxinc/nginx-saml

Справочная реализация NGINX Plus в качестве поставщика услуг для аутентификации SAML.

https://github.com/nginxinc/njs-prometheus-module

Предоставляет конечную точку метрик Prometheus напрямую из NGINX Plus.

[!TIP] NJS также может использоваться с NGINX Unit сервером приложений. Узнайте больше о Control API NGINX Unit и о том, как определять вызовы функций с помощью NJS.

Загрузка и установка

Следуйте этим шагам, чтобы загрузить и установить предварительно скомпилированные бинарные файлы NGINX и NGINX JavaScript для Linux. Вы также можете выбрать сборку модуля локально из исходного кода.

Подготовка репозитория пакетов NGINX

Следуйте этому руководству, чтобы добавить официальный репозиторий пакетов NGINX в вашу систему и установить NGINX Open Source. Если у вас уже установлен NGINX Open Source или NGINX Plus, пропустите часть установки NGINX в последнем шаге.

Начало работы с NGINX JavaScript

Использование NJS включает в себя активацию модуля, добавление файлов JavaScript с определенными функциями и вызов экспортированных функций в конфигурационных файлах NGINX.

Проверьте, что NGINX работает

NGINX JavaScript является модулем для NGINX Open Source или NGINX Plus. Если вы еще этого не сделали, выполните следующие шаги, чтобы установить NGINX Open Source или NGINX Plus. После установки убедитесь, что экземпляр NGINX работает и может отвечать на HTTP-запросы.

Запуск NGINX

Выполните следующую команду для запуска NGINX:

sudo nginx

Проверьте, что NGINX отвечает на HTTP-запросы

curl -I 127.0.0.1

Вы должны увидеть следующий ответ:

HTTP/1.1 200 OK
Server: nginx/1.25.5

Включение модулей NGINX JavaScript

После установки один (или оба) модуля NJS должны быть включены в конфигурационный файл NGINX. На большинстве систем конфигурационный файл NGINX по умолчанию находится по адресу /etc/nginx/nginx.conf.

Редактирование конфигурационного файла NGINX

sudo vi /etc/nginx/nginx.conf

Включение динамической загрузки модулей NJS

Используйте директиву load_module в верхнем уровне (“главном”) контексте, чтобы включить один (или оба) модуля.

load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so;

Основы написания .js файлов скриптов

Файлы скриптов NJS обычно имеют расширение .js и размещаются в каталоге /etc/nginx/njs/. Они обычно состоят из функций, которые затем экспортируются, делая их доступными в конфигурационных файлах NGINX.

Справочник по пользовательским объектам, методам и свойствам

NJS предоставляет коллекцию объектов с ассоциированными методами и свойствами, которые не являются частью определений ECMAScript. См. полный справочник на эти объекты и то, как они могут быть использованы для дальнейшего расширения и настройки NGINX.

Пример: Hello World

Вот базовый пример "Hello World".

example.js

Функция hello в этом файле возвращает код состояния HTTP 200 OK вместе со строкой "Hello World!", за которой следует перевод строки. Функция затем экспортируется для использования в конфигурационном файле NGINX.

Добавьте этот файл в каталог /etc/nginx/njs:

function hello(r) {
  r.return(200, "Hello world!\n");
}

export default {hello}

nginx.conf

Мы изменяем нашу конфигурацию NGINX (/etc/nginx/nginx.conf), чтобы импортировать файл JavaScript и выполнять функцию при определенных обстоятельствах.

# Загрузить модуль ngx_http_js_module
load_module modules/ngx_http_js_module.so;

events {}

http {
  # Установите путь к нашим njs JavaScript файлам
  js_path "/etc/nginx/njs/";

  # Импортируем наш JavaScript файл в переменную "main"
  js_import main from http/hello.js;

  server {
    listen 80;

    location / {
      # Выполнить функцию "hello", определенную в нашем JavaScript файле для всех HTTP запросов
      # и ответить содержимым нашей функции.
      js_content main.hello;
    }
  }
}

Для полного списка директив njs смотрите страницы документации ngx_http_js_module и ngx_stream_js_module.

[!TIP] Более подробная версия этого и других примеров доступна в официальном репозитории njs-examples.

Интерфейс командной строки NJS (CLI)

NGINX JavaScript устанавливается с утилитой интерфейса командной строки. Интерфейс может быть открыт как интерактивная оболочка или использован для обработки синтаксиса JavaScript из предопределенных файлов или стандартного ввода. Поскольку утилита работает независимо, специфические для NGINX объекты, такие как HTTP и Stream, недоступны в его среде выполнения.

Пример использования интерактивного CLI

$ njs
>> globalThis
global {
  njs: njs {
    version: '0.8.4'
  },
  global: [Circular],
  process: process {
    argv: ['/usr/bin/njs'],
    env: {
      PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
      HOSTNAME: 'f777c149d4f8',
      TERM: 'xterm',
      NGINX_VERSION: '1.25.5',
      NJS_VERSION: '0.8.4',
      PKG_RELEASE: '1~buster',
      HOME: '/root'
    }
  },
  console: {
    log: [Function: native],
    dump: [Function: native],
    time: [Function: native],
    timeEnd: [Function: native]
  },
  print: [Function: native]
}
>>

Пример использования неинтерактивного CLI

$ echo "2**3" | njs -q
8

Клонирование репозитория NGINX JavaScript на GitHub

Используя предпочитаемый вами метод, клонируйте репозиторий NGINX JavaScript в ваш каталог разработки. См. Клонирование репозитория GitHub для получения дополнительной помощи.

https://github.com/nginx/njs.git

Настройка и сборка

Запустите следующие команды из корневого каталога вашего клонированного репозитория:

./configure

Соберите NGINX JavaScript:

make

Утилита теперь должна быть доступна по адресу <NJS_SRC_ROOT_DIR>/build/njs. См. Интерфейс командной строки NJS (CLI) для получения информации о использовании.

Клонирование репозитория NGINX на GitHub

Клонируйте репозиторий исходного кода NGINX в каталог, находящийся вне ранее клонированного репозитория исходного кода NJS.

https://github.com/nginx/nginx.git

Технические характеристики NGINX JavaScript

Технические характеристики NJS идентичны характеристикам NGINX.

Поддерживаемые дистрибутивы

См. Проверенные операционные системы и платформы для полного списка поддерживаемых дистрибутивов.

Поддерживаемые среды развертывания

Контейнер
Облачные сервисы (AWS, Google Cloud Platform, Microsoft Azure)
Виртуальная машина

Поддерживаемые версии NGINX

NGINX JavaScript поддерживается всеми версиями NGINX Open Source, начиная с nginx-1.14, и всеми версиями NGINX Plus, начиная с NGINX Plus R15.

Задавайте вопросы, сообщайте о проблемах и вносите вклад

Мы призываем вас взаимодействовать с нами. Пожалуйста, смотрите руководство по вкладу для получения информации о том, как задавать вопросы, сообщать о проблемах и вносить код.

Журнал изменений

Смотрите нашу страницу релизов, чтобы отслеживать обновления.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-njs.