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 в верхнем уровне (“main”) контексте, чтобы включить один (или оба) модуля.

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 {
  # Установить путь к нашим JavaScript файлам njs
  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.

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

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

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

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

GitHub

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