跳转至

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

项目状态：活跃 – 项目已达到稳定、可用状态，并正在积极开发中。 社区支持

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 开源版 或 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 开源版。如果您已经安装了 NGINX 开源版或 NGINX Plus，请跳过最后一步中的 NGINX 安装部分。

开始使用 NGINX JavaScript

使用 NJS 涉及启用模块、添加具有定义函数的 JavaScript 文件，并在 NGINX 配置文件中调用导出的函数。

验证 NGINX 是否正在运行

NGINX JavaScript 是 NGINX 开源版或 NGINX Plus 的一个模块。如果您尚未完成，请按照以下步骤安装 NGINX 开源版 或 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 开源版和所有从 NGINX Plus R15 开始的 NGINX Plus 版本。

提问、报告问题和贡献

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

更新日志

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

GitHub

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