用于 nginx 的 JavaScript 语言的子集
NGINX JavaScript, also known as NJS, is a dynamic module for NGINX that enables the extension of built-in functionality using familiar JavaScript syntax. NJS supports modern JavaScript through its recommended QuickJS engine (ES2023). See JavaScript engines and compatibility for more details.
NGINX JavaScript is provided as two dynamic modules for NGINX (ngx_http_js_module and ngx_stream_js_module) and can be added to any supported NGINX Open Source or NGINX Plus installation without recompilation.
The NJS module allows NGINX administrators to:
See examples and our various projects developed with NJS:
Extends NGINX Plus functionality to communicate directly with OIDC-compatible Identity Providers, authenticating users and authorizing content delivered by NGINX Plus.
Reference implementation of NGINX Plus as a service provider for SAML authentication.
Exposes Prometheus metrics endpoint directly from NGINX Plus.
[!TIP] NJS can also be used with the NGINX Unit application server. Learn more about NGINX Unit's Control API and how to define function calls with NJS.
NJS provides two interchangeable JavaScript engines, selectable with the js_engine directive:
js_engine qjs;. Building from source requires the QuickJS library (see Building from source). Read more: QuickJS engine support for NJS.See engine selection and compatibility for details.
Follow these steps to download and install precompiled NGINX and NGINX JavaScript Linux binaries. You may also choose to build the module locally from source code.
Follow this guide to add the official NGINX package repository to your system and install NGINX Open Source. If you already have NGINX Open Source or NGINX Plus installed, skip the NGINX installation portion in the last step.
Once the repository has been provisioned, you may install NJS by issuing the following command:
sudo apt install nginx-module-njs
sudo yum install nginx-module-njs
sudo apk add nginx-module-njs@nginx
sudo zypper install nginx-module-njs
[!TIP] The package repository includes an alternate module that enables debug symbols. Although not recommended for production environments, this module may be helpful when developing NJS-based configurations. To download and install the debug version of the module, replace the module name in the previous command with
nginx-module-njs-dbg.
The package installation scripts install two modules, supporting NGINX http and stream contexts.
This NJS module enables manipulation of data transmitted over HTTP.
This NJS module enables manipulation of data transmitted via stream protocols such as TCP and UDP.
By default, both modules are installed into the /etc/nginx/modules directory.
Usage of NJS involves enabling the module, adding JavaScript files with defined functions, and invoking exported functions in NGINX configuration files.
NGINX JavaScript is a module for NGINX Open Source or NGINX Plus. If you haven't done so already, follow these steps to install NGINX Open Source or NGINX Plus. Once installed, ensure the NGINX instance is running and able to respond to HTTP requests.
Issue the following command to start NGINX:
sudo nginx
curl -I 127.0.0.1
You should see the following response:
HTTP/1.1 200 OK
Server: nginx/1.25.5
Once installed, either (or both) NJS module(s) must be included in the NGINX configuration file. On most systems, the NGINX configuration file is located at /etc/nginx/nginx.conf by default.
sudo vi /etc/nginx/nginx.conf
Use the load_module directive in the top-level (“main”) context to enable either (or both) module(s).
load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so;
NJS script files are typically named with a .js extension and placed in the /etc/nginx/njs/ directory. They are usually comprised of functions that are then exported, making them available in NGINX configuration files.
NJS provides a collection of objects with associated methods and properties that are not part of ECMAScript definitions. See the complete reference to these objects and how they can be used to further extend and customize NGINX.
Here's a basic "Hello World" example.
The hello function in this file returns an HTTP 200 OK status response code along with the string "Hello World!", followed by a line feed. The function is then exported for use in an NGINX configuration file.
Add this file to the /etc/nginx/njs directory:
function hello(r) {
r.return(200, "Hello world!\n");
}
export default {hello}
We modify our NGINX configuration (/etc/nginx/nginx.conf) to import the JavaScript file and execute the function under specific circumstances.
# Load the ngx_http_js_module 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 example.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;
}
}
}
For a full list of njs directives, see the ngx_http_js_module and ngx_stream_js_module module documentation pages.
[!TIP] A more detailed version of this and other examples can be found in the official njs-examples repository.
NGINX JavaScript installs with a command line interface utility. The interface can be opened as an interactive shell or used to process JavaScript syntax from predefined files or standard input. Since the utility runs independently, NGINX-specific objects such as HTTP and Stream are not available within its runtime.
$ 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:
暂无开放 Issues，或尚未同步最近议题。