nginx/njs

[](https://www.repostatus.org/#active) [](/SUPPORT.md)  # NGINX JavaScript NGINX JavaScript，也称为 [NJS](https://nginx.org/en/docs/njs/)，是 [NGINX](https://nginx.org/en/download.html) 的一个动态模块，它允许使用熟悉的 JavaScript 语法来扩展内置功能。NJS 通过其推荐的 [QuickJS 引擎](#javascript-engines) (ES2023) 支持现代 JavaScript。有关更多详细信息，请参阅 [JavaScript 引擎](#javascript-engines) 和 [兼容性](https://nginx.org/en/docs/njs/compatibility.html)。 # 目录 - [工作原理](#how-it-works) - [JavaScript 引擎](#javascript-engines) - [下载和安装](#downloading-and-installing) - [配置 NGINX 软件包仓库](#provisioning-the-nginx-package-repository) - [安装 NGINX JavaScript 模块](#installing-the-nginx-javascipt-modules) - [已安装的文件和位置](#installed-files-and-locations) - [NGINX JavaScript 入门](#getting-started-with-nginx-javascript) - [验证 NGINX 是否正在运行](#verify-nginx-is-running) - [启用 NGINX JavaScript 模块](#enabling-the-nginx-javascipt-modules) - [编写 .js 脚本文件的基础知识](#basics-of-writing-js-script-files) - [自定义对象、方法和属性参考](#reference-of-custom-objects-methods-and-properties) - [示例：Hello World](#example-hello-world) - [NJS 命令行界面 (CLI)](#the-njs-command-line-interface-cli) - [从源代码构建](#building-from-source) - [安装依赖项](#installing-dependencies) - [克隆 NGINX JavaScript GitHub 仓库](#cloning-the-nginx-javascript-github-repository) - [构建独立命令行界面实用程序（可选）](#building-standalone-command-line-interface-utility-optional) - [克隆 NGINX GitHub 仓库](#cloning-the-nginx-github-repository) - [将 NGINX JavaScript 作为 NGINX 的模块进行构建](#building-nginx-javascript-as-a-module-of-nginx) - [NGINX JavaScript 技术规格](#nginx-javascript-technical-specifications) - [支持的发行版](#supported-distributions) - [支持的部署环境](#supported-deployment-environments) - [支持的 NGINX 版本](#supported-nginx-versions) - [配置建议](#sizing-recommendations) - [提问、报告问题和贡献](#asking-questions-reporting-issues-and-contributing) - [更新日志](#change-log) - [许可证](#license) # 工作原理 [NGINX JavaScript](https://nginx.org/en/docs/njs/) 作为 NGINX 的两个[动态模块](https://nginx.org/en/linux_packages.html#dynmodules)（[ngx_http_js_module](https://nginx.org/en/docs/http/ngx_http_js_module.html) 和 [ngx_stream_js_module](https://nginx.org/en/docs/stream/ngx_stream_js_module.html)）提供，无需重新编译即可添加到任何受支持的 [NGINX 开源版本](https://nginx.org/en/download.html) 或 [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) 安装中。 NJS 模块允许 NGINX 管理员： - 在请求到达上游服务器之前添加复杂的访问控制和安全检查 - 修改响应标头 - 编写灵活的、异步的内容处理程序、过滤器等等！ 请参阅[示例](https://github.com/nginx/njs-examples/)以及我们使用 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 指标端点。 # JavaScript 引擎 NJS 提供了两种可互换的 JavaScript 引擎，可通过 [js_engine](https://nginx.org/en/docs/http/ngx_http_js_module.html#js_engine) 指令进行选择： - **QuickJS（推荐）** — 符合 [ES2023](https://262.ecma-international.org/14.0/) 规范的现代引擎。使用 `js_engine qjs;` 启用它。从源码构建需要 QuickJS 库（参见[从源码构建](#building-from-source)）。了解更多：[NJS 的 QuickJS 引擎支持](https://blog.nginx.org/blog/quickjs-engine-support-for-njs)。 - **内置 njs 引擎（自 1.0.0 起弃用）** — 原始引擎，它是符合 [ES5.1](https://262.ecma-international.org/5.1/)（[严格变体](https://262.ecma-international.org/5.1/#sec-4.2.2)）规范的 JavaScript 子集，外加一组精选的 [ES6](https://262.ecma-international.org/6.0/) 及更新的扩展。它目前是默认引擎，在可预见的将来将继续受支持并修复其 Bug。我们建议迁移到 QuickJS；最终 QuickJS 将成为默认引擎，而 njs 引擎将作为兼容性选项保留。 有关详细信息，请参阅[引擎选择](https://nginx.org/en/docs/njs/engine.html)和[兼容性](https://nginx.org/en/docs/njs/compatibility.html)。 # 下载和安装 按照以下步骤下载并安装预编译的 NGINX 和 NGINX JavaScript Linux 二进制文件。您也可以选择[从源代码在本地构建模块](#building-from-source)。 ## 配置 NGINX 软件包仓库 请按照[此指南](https://nginx.org/en/linux_packages.html)将官方 NGINX 软件包仓库添加到您的系统并安装 NGINX 开源版本。如果您已经安装了 NGINX 开源版本或 NGINX Plus，请跳过最后一步中的 NGINX 安装部分。 ## 安装 NGINX JavaScript 模块 配置好仓库后，您可以通过发出以下命令来安装 NJS： ### 基于 Ubuntu 或 Debian 的系统 ``` sudo apt install nginx-module-njs ``` ### RHEL、RedHat 及其衍生版本 ``` sudo yum install nginx-module-njs ``` ### Alpine 或类似系统 ``` sudo apk add nginx-module-njs@nginx ``` ### SuSE、SLES 或类似系统 ``` sudo zypper install nginx-module-njs ``` ## 已安装的文件和位置 软件包安装脚本会安装两个模块，以支持 NGINX 的 [`http`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) 和 [`stream`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) 上下文。 - [ngx_http_js_module](https://nginx.org/en/docs/http/ngx_http_js_module.html) 该 NJS 模块允许操作通过 HTTP 传输的数据。 - [ngx_stream_js_module](https://nginx.org/en/docs/stream/ngx_stream_js_module.html) 该 NJS 模块允许操作通过 TCP 和 UDP 等 stream 协议传输的数据。 默认情况下，这两个模块都安装到 `/etc/nginx/modules` 目录中。 # NGINX JavaScript 入门 NJS 的使用包括启用模块、添加包含已定义函数的 JavaScript 文件，以及在 NGINX 配置文件中调用导出的函数。 ## 验证 NGINX 是否正在运行 NGINX JavaScript 是 NGINX 开源版本或 NGINX Plus 的一个模块。如果您尚未安装，请按照以下步骤安装 [NGINX 开源版本](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) 或 [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-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 模块的动态加载 在顶级（“main”）上下文中使用 [load_module](https://nginx.org/en/docs/ngx_core_module.html#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 定义。请参阅[完整参考](https://nginx.org/en/docs/njs/reference.html)以了解这些对象，以及如何使用它们来进一步扩展和自定义 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 { # Set the path to our njs JavaScript files js_path "/etc/nginx/njs/"; # Import our JavaScript file into the variable "main" js_import main from http/hello.js; server { listen 80; location / { # Execute the "hello" function defined in our JavaScript file on all HTTP requests # and respond with the contents of our function. js_content main.hello; } } } ``` 有关 njs 指令的完整列表，请参阅 [ngx_http_js_module](https://nginx.org/en/docs/http/ngx_http_js_module.html) 和 [ngx_stream_js_module](https://nginx.org/en/docs/stream/ngx_stream_js_module.html) 模块文档页面。 ## NJS 命令行界面 (CLI) NGINX JavaScript 安装时会附带一个命令行界面实用程序。该界面可以作为交互式 shell 打开，也可以用于处理来自预定义文件或标准输入的 JavaScript 语法。由于该实用程序独立运行，因此在其 runtime 中无法使用 NGINX 特定的对象，例如 [HTTP](https://nginx.org/en/docs/njs/reference.html#http) 和 [Stream](https://nginx.org/en/docs/njs/reference.html#http)。 ### 交互式 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 构建为动态模块以集成到 NGINX 中，或者构建为用作命令行界面实用程序的独立二进制文件。 ## 安装依赖项 大多数 Linux 发行版都需要安装几个依赖项才能构建 NGINX 和 NGINX JavaScript。以下说明专门针对 `apt` 软件包管理器，该管理器在大多数 Ubuntu/Debian 发行版及其衍生版本上广泛可用。 ### 安装编译器和 make 实用程序 ``` sudo apt install gcc make ``` ### 安装依赖库 ``` sudo apt install libpcre3-dev zlib1g-dev libssl-dev libxml2-dev libxslt-dev ``` 要使用 [QuickJS](https://nginx.org/en/docs/njs/engine.html) 进行构建，您还需要构建 QuickJS 库： ``` git clone https://github.com/bellard/quickjs cd quickjs CFLAGS='-fPIC' make libquickjs.a ``` ## 克隆 NGINX JavaScript GitHub 仓库 使用您偏好的方法，将 NGINX JavaScript 仓库克隆到您的开发目录中。有关更多帮助，请参阅[克隆 GitHub 仓库](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)。 ``` https://github.com/nginx/njs.git ``` ## 构建独立命令行界面实用程序（可选） 以下步骤是可选的，仅当您选择将 NJS 构建为独立实用程序时才需要。 ### 安装依赖项 要使用 NJS 交互式 shell，您需要安装 libedit-dev 库 ``` sudo apt install libedit-dev ``` ### 配置和构建 在您克隆的仓库的根目录中运行以下命令： ``` ./configure ``` 构建 NGINX JavaScript： ``` make ``` 该实用程序现在应该位于 `/build/njs`。有关使用信息，请参阅 [NJS 命令行界面 (CLI)](#the-njs-command-line-interface-cli)。 ## 克隆 NGINX GitHub 仓库 将 NGINX 源代码仓库克隆到之前克隆的 NJS 源代码仓库之外的目录中。 ``` https://github.com/nginx/nginx.git ``` ## 将 NGINX JavaScript 作为 NGINX 的模块进行构建 要将 NGINX JavaScript 构建为动态模块，请从 NGINX 源代码仓库的根目录执行以下命令： ``` auto/configure --add-dynamic-module=/nginx ``` 要构建支持 [QuickJS](https://nginx.org/en/docs/njs/engine.html) 的版本，请使用 `--with-cc-opt=` 和 `--with-ld-opt=` 选项提供 include 和库路径： ``` auto/configure --add-dynamic-module=/nginx \ --with-cc-opt="-I" \ --with-ld-opt="-L" ``` 编译模块 ``` make ``` ### 安装模块 如果构建为动态模块，NGINX JavaScript 模块将位于 `/objs/` 目录中。然后可以将该模块复制到现有的 NGINX 安装中并启用。有关详细信息，请参阅[启用 NGINX JavaScript 模块](#enabling-the-nginx-javascipt-modules)。 ### 安装已编译的 NGINX 和 NGINX JavaScript 二进制文件 或者，您可以选择通过发出以下命令来安装构建好的 NGINX 和 NGINX JavaScript 二进制文件： ``` make install ``` 默认情况下，NGINX 二进制文件将安装到 `/usr/local/nginx/sbin/nginx`。NGINX JavaScript 模块将被复制到 `/usr/local/nginx/modules/`。 # NGINX JavaScript 技术规格 NJS 的技术规格与 NGINX 相同。 ## 支持的发行版 有关受支持的发行版的完整列表，请参阅[已测试操作系统和平台](https://nginx.org/en/#tested_os_and_platforms)。 ## 支持的部署环境 - 容器 - 公有云（AWS、Google Cloud Platform、Microsoft Azure） - 虚拟机 ## 支持的 NGINX 版本 从 nginx-1.14 开始的所有 NGINX 开源版本以及从 NGINX Plus R15 开始的所有 NGINX Plus 版本均支持 NGINX JavaScript。 # 提问、报告问题和贡献 我们鼓励您与我们互动。有关如何提问、报告问题和贡献代码的信息，请参阅[贡献指南](CONTRIBUTING.md)。 # 更新日志 请参阅我们的[发布页面](https://nginx.org/en/docs/njs/changes.html)以跟踪更新。 # 许可证 [类似 BSD 条款的 2 句版许可证](LICENSE) 更多文档请访问：https://nginx.org/en/docs/njs/ ©2024 F5, Inc. 保留所有权利。 https://www.f5.com/products/nginx

标签：CMS安全, JavaScript, NGINX, SOC Prime, Web服务器, 动态模块, 客户端加密, 开发工具, 数据可视化, 脚本扩展, 负责任AI