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，于 2026 年 3 月 3 日发布。

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 管理员： - 在请求到达上游服务器之前添加复杂的访问控制和安全检查 - 操作响应头 - 编写灵活的异步内容处理程序、过滤器等！

请参见示例以及我们使用 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

直接从 NGINX Plus 暴露 Prometheus 指标端点。

[!TIP] NJS 还可以与 NGINX Unit 应用服务器一起使用。了解有关 NGINX Unit 的控制 API 以及如何使用 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 模块

安装后，必须在 NGINX 配置文件中包含 NJS 模块（或两个模块）。在大多数系统中，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 / {
      # 在所有 HTTP 请求上执行我们 JavaScript 文件中定义的 "hello" 函数
      # 并响应我们函数的内容。
      js_content main.hello;
    }
  }
}

有关 njs 指令的完整列表，请参见 ngx_http_js_module 和 ngx_stream_js_module 模块文档页面。

[!TIP] 此示例及其他示例的更详细版本可以在官方 njs-examples 仓库中找到。

NJS 命令行界面 (CLI)

NGINX JavaScript 安装时附带命令行界面实用程序。该接口可以作为交互式 shell 打开，或用于处理来自预定义文件或标准输入的 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 仓库

在之前克隆的 NJS 源代码仓库之外的目录中克隆 NGINX 源代码仓库。

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

NGINX JavaScript 技术规格

NJS 的技术规格与 NGINX 相同。

支持的发行版

有关支持的发行版的完整列表，请参见测试的操作系统和平台。

支持的部署环境

容器
公有云（AWS、Google Cloud Platform、Microsoft Azure）
虚拟机

支持的 NGINX 版本

NGINX JavaScript 支持所有从 nginx-1.14 开始的 NGINX Open Source 版本，以及所有从 NGINX Plus R15 开始的 NGINX Plus 版本。

提问、报告问题和贡献

我们鼓励您与我们互动。有关如何提问、报告问题和贡献代码的信息，请参见贡献指南。

更新日志

请参见我们的发布页面以跟踪更新。

GitHub

您可以在 nginx-module-njs 的 GitHub 仓库中找到此模块的其他配置提示和文档。