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.5, выпущенный 13 января 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.

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

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

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

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

GitHub

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