全栈攻城狮

Appearance

njs 参考文档 ​

提示

来自deepseek解释

原文链接：https://nginx.org/en/docs/njs/reference.html

本参考文档仅包含 njs 特有的、不符合 ECMAScript 标准的属性、方法和模块。符合 ECMAScript 标准的 njs 属性和方法定义请参见 ECMAScript 规范。所有 njs 属性和方法的完整列表请参见 兼容性。

nginx 对象 ​

HTTP 请求对象（HTTP Request） ​

HTTP 请求对象仅在 ngx_http_js_module 模块中可用。

在 0.8.5 版本之前，该对象的所有字符串属性均为字节字符串。

r.args{} ​

请求参数对象，只读。

查询字符串以对象形式返回。自 0.7.6 版本起：

  • 重复的键以数组形式返回
  • 键名区分大小写
  • 键和值均进行百分号解码

例如，查询字符串 'a=1&b=%32&A=3&b=4&B=two%20words' 转换为 r.args 为：

js
{a: "1", b: ["2", "4"], A: "3", B: "two words"}

更高级的解析场景可使用查询字符串模块或 $args 变量：

js
import qs from 'querystring';

function args(r) {
    return qs.parse(r.variables.args);
}

参数对象在首次访问 r.args 时求值。如果只需要单个参数（如 foo），可使用 nginx 变量：

js
r.variables.arg_foo

此处 nginx 变量对象 返回给定键的第一个值，不区分大小写，且不进行百分号解码。

要将 r.args 转换回字符串，可使用查询字符串的 stringify 方法。

r.decline() ​

使 js_access 处理程序对访问权限不发表意见，将决策权交给 satisfy any 下的其他访问检查器（0.9.9）。

未调用 r.decline() 或 r.return() 即返回的处理程序，隐式授予访问权限。

仅可在 js_access 函数中调用。

r.done() ​

调用此函数后，后续数据块将直接传递给客户端，而不再调用 js_body_filter（0.5.2）。

仅可在 js_body_filter 函数中调用。

r.error(string) ​

将字符串写入错误日志的 error 级别。

注意：由于 nginx 有硬编码的最大行长度限制，仅可记录字符串的前 2048 字节。

r.finish() ​

完成向客户端发送响应。

r.headersIn{} ​

入站请求头对象，只读。

Foo 请求头可通过以下语法访问：

js
headersIn.foo
headersIn['Foo']

以下请求头只能有一个字段值（0.4.1）：

  • Authorization、Content-Length、Content-Range、Content-Type、ETag、Expect、From、Host、If-Match、If-Modified-Since、If-None-Match、If-Range、If-Unmodified-Since、Max-Forwards、Proxy-Authorization、Referer、Transfer-Encoding、User-Agent

“Cookie” 头中的重复字段值以分号（;）分隔。所有其他请求头中的重复字段值以逗号分隔。

r.headersOut{} ​

主请求的出站响应头对象，可写。

如果 r.headersOut{} 是子请求的响应对象，则它表示响应头。在此情况下，以下响应头的字段值可能被忽略：

  • Accept-Ranges、Connection、Content-Disposition、Content-Encoding、Content-Length、Content-Range、Date、Keep-Alive、Server、Transfer-Encoding、X-Accel-*

Foo 响应头可通过以下语法访问：

js
headersOut.foo
headersOut['Foo']

出站响应头应在响应头发送给客户端之前设置，否则头更新将被忽略。这意味着 r.headersOut{} 在以下位置可写：

多值响应头的字段值（0.4.0）可通过以下语法设置：

js
r.headersOut['Foo'] = ['a', 'b']

输出结果为：

Foo: a
Foo: b

“Foo” 响应头的所有先前字段值将被删除。

对于只接受单个字段值的标准响应头（如 “Content-Type”），仅数组的最后一个元素生效。

“Set-Cookie” 响应头的字段值始终以数组形式返回。

以下响应头中的重复字段值将被忽略：

  • Age、Content-Encoding、Content-Length、Content-Type、ETag、Expires、Last-Modified、Location、Retry-After

所有其他响应头中的重复字段值以逗号分隔。

r.httpVersion ​

HTTP 版本，只读。

r.internal ​

布尔值，对于内部 location 为 true。

r.internalRedirect(uri) ​

执行到指定 uri 的内部重定向。

如果 uri 以 “@” 前缀开头，则视为命名 location。

在新 location 中，所有请求处理将重新开始：

  • 普通 location：从 NGX_HTTP_SERVER_REWRITE_PHASE 开始
  • 命名 location：从 NGX_HTTP_REWRITE_PHASE 开始

因此，重定向到命名 location 不会检查 client_max_body_size 限制。

重定向后的请求变为内部请求，可以访问内部 location。

实际重定向在处理程序执行完成后发生。

注意：重定向后，目标 location 中会启动一个新的 njs VM，原始 location 中的 VM 将停止。nginx 变量的值会被保留，可用于向目标 location 传递信息。自 0.5.3 起，可使用通过 js_var 指令（http 或 stream）声明的变量。

注意：自 0.7.4 起，该方法接受转义后的 URI。

r.log(string) ​

将字符串写入错误日志的 info 级别。

注意：由于 nginx 有硬编码的最大行长度限制，仅可记录字符串的前 2048 字节。

r.method ​

HTTP 方法，只读。

r.parent ​

引用父请求对象。

r.remoteAddress ​

客户端地址，只读。

r.readRequestArrayBuffer() ​

返回一个 Promise，解析为包含客户端请求体的 ArrayBuffer（0.9.9）。

可用性、请求体缓存和并发语义请参见 r.readRequestText()。

r.readRequestForm([options]) ​

读取客户端请求体并将其解析为 HTML 表单，返回一个 Promise，解析为表单对象（0.9.9）。

支持的内容类型：

  • application/x-www-form-urlencoded
  • multipart/form-data

表单对象提供以下方法：

  • get(name) — 返回 name 的第一个值，若不存在则返回 null
  • getAll(name) — 返回 name 的所有值的数组
  • has(name) — 如果至少存在一个条目则返回 true
  • forEach(callback[, thisArg]) — 对每个条目调用 callback，参数为 (value, key, form)
  • hasFiles() — 如果表单包含任何文件部分则返回 true

对于文本字段，值为解码后的字符串。对于文件部分，值为一个对象，客户端提供的文件名可作为 name 属性访问；文件内容不会暴露。文件名由客户端提供，未经清理。

可选的 options 对象接受以下属性：

  • maxKeys（数字）— 要解析的最大字段数，默认值为 128。超出限制将拒绝返回的 promise。

可用性、请求体缓存和并发语义请参见 r.readRequestText()。解析后的表单会在请求上缓存：后续调用将返回相同的表单对象，并忽略新的 options 参数。

r.readRequestJSON() ​

返回一个 Promise，解析为将客户端请求体解析为 JSON 的结果（0.9.9）。

可用性、请求体缓存和并发语义请参见 r.readRequestText()。

r.readRequestText() ​

返回一个 Promise，解析为包含客户端请求体的字符串（0.9.9）。

请求体的大小受 client_max_body_size 限制。

该方法在 js_access 和 js_content 指令中可用。

请求体会被读取一次并在请求上缓存：后续调用 r.readRequestText()、r.readRequestArrayBuffer()、r.readRequestJSON() 或 r.readRequestForm() 将从缓存中解析，而不会重新读取网络数据。

如果在前一次读取尚未完成时发起第二次调用，将抛出 “request body is already being read” 错误。

注意：它可能会将 UTF-8 编码中无效的字节转换为替换字符。

r.requestBody ​

该属性在 0.5.0 版本中已弃用，并在 0.8.0 版本中移除。应使用 r.requestBuffer 或 r.requestText 属性。

r.requestBuffer ​

客户端请求体（如果尚未写入临时文件）（自 0.5.0）。

为确保客户端请求体在内存中，其大小应受 client_max_body_size 限制，并使用 client_body_buffer_size 设置足够的缓冲区大小。

该属性仅在 js_content 指令中可用。

对于异步访问或在 js_access 中使用，请参见 r.readRequestText() 及其他 r.readRequest*() 方法。

r.requestText ​

与 r.requestBuffer 相同，但返回字符串（自 0.5.0）。

注意：它可能会将 UTF-8 编码中无效的字节转换为替换字符。

对于异步访问或在 js_access 中使用，请参见 r.readRequestText()。

r.rawHeadersIn[] ​

返回一个键值对数组，内容与从客户端接收到的完全一致（0.4.1）。

例如，对于以下请求头：

Host: localhost
Foo: bar
foo: bar2

r.rawHeadersIn 的输出为：

js
[ ['Host', 'localhost'], ['Foo', 'bar'], ['foo', 'bar2'] ]

可通过以下语法收集所有 foo 头：

js
r.rawHeadersIn.filter(v => v[0].toLowerCase() == 'foo').map(v => v[1])

输出为：['bar', 'bar2']

头字段名称不会转换为小写，重复字段值不会合并。

r.rawHeadersOut[] ​

返回响应头的键值对数组（0.4.1）。

头字段名称不会转换为小写，重复字段值不会合并。

r.responseBody ​

该属性在 0.5.0 版本中已弃用，并在 0.8.0 版本中移除。应使用 r.responseBuffer 或 r.responseText 属性。

r.responseBuffer ​

子请求响应体，只读（自 0.5.0）。

r.responseBuffer 的大小受 subrequest_output_buffer_size 指令限制。

r.responseText ​

与 r.responseBuffer 相同，但返回字符串（自 0.5.0）。

注意：它可能会将 UTF-8 编码中无效的字节转换为替换字符。

r.return(status[, string | Buffer]) ​

向客户端发送带有指定 status 的完整响应。

响应可以是字符串或 Buffer（0.5.0）。

可以指定重定向 URL（对于状态码 301、302、303、307 和 308）或响应体文本（对于其他状态码）作为第二个参数。

r.send(string | Buffer) ​

向客户端发送响应体的一部分。

发送的数据可以是字符串或 Buffer（0.5.0）。

r.sendBuffer(data[, options]) ​

将数据添加到数据块链中，以便转发给下一个 body 过滤器（0.5.2）。

实际转发稍后发生，在当前链的所有数据块处理完成后。

数据可以是字符串或 Buffer。

options 是一个对象，用于覆盖从传入数据块缓冲区派生的 nginx 缓冲区标志。

可覆盖的标志：

  • last（布尔值）— 如果缓冲区是最后一个缓冲区则为 true
  • flush（布尔值）— 如果缓冲区应设置 flush 标志则为 true

r.sendHeader() ​

向客户端发送 HTTP 头。

r.setReturnValue(value) ​

设置 js_set 处理程序的返回值（0.7.0）。

与普通的 return 语句不同，当处理程序是 JS 异步函数时，应使用此方法。

例如：

js
async function js_set(r) {
    const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
    r.setReturnValue(digest);
}

r.status ​

状态码，可写。

r.subrequest(uri[, options[, callback]]) ​

使用给定的 uri 和 options 创建子请求，并安装可选的完成回调。

子请求与客户端请求共享其输入头。要向代理服务器发送与原始头不同的头，可使用 proxy_set_header 指令。要向代理服务器发送全新的头集，可使用 proxy_pass_request_headers 指令。

如果 options 是字符串，则它包含子请求的参数字符串。否则，options 应为包含以下键的对象：

  • args — 参数字符串，默认使用空字符串
  • body — 请求体，默认使用父请求对象的请求体
  • method — HTTP 方法，默认使用 GET 方法
  • detached — 布尔标志（0.3.9），如果为 true，则创建的子请求为分离子请求。分离子请求的响应将被忽略。与普通子请求不同，分离子请求可以在变量处理程序内部创建。detached 标志与 callback 参数互斥。

完成回调接收一个子请求响应对象，其方法和属性与父请求对象相同。

自 0.3.8 起，如果未提供回调，则返回一个 Promise，解析为子请求响应对象。

例如，查看子请求中的所有响应头：

js
async function handler(r) {
    const reply = await r.subrequest('/path');
    for (const h in reply.headersOut) {
        r.log(`${h}: ${reply.headersOut[h]}`);
    }
    r.return(200);
}

r.uri ​

当前请求中的 URI，已规范化，只读。

r.rawVariables{} ​

nginx 变量，以 Buffer 形式表示，可写（自 0.5.0）。

r.jsVarNames([prefix]) ​

返回一个包含通过 js_var 指令声明的 nginx 变量名称的新数组（自 0.9.9）。

可选的 prefix 参数必须为字符串。如果指定，则仅返回以该前缀开头的名称。

r.variables{} ​

nginx 变量对象，可写（自 0.2.8）。

例如，获取 $foo 变量，可使用以下语法之一：

js
r.variables['foo']
r.variables.foo

自 0.8.6 起，可通过以下语法访问正则表达式捕获组：

js
r.variables['1']
r.variables[1]

nginx 对在 nginx.conf 中被引用的变量和未被引用的变量处理方式不同。当变量被引用时，它可能是可缓存的；但当未被引用时，它始终是不可缓存的。

例如，当 $request_id 变量仅从 njs 访问时，每次求值都会得到一个新值。但当 $request_id 被引用时（例如 proxy_set_header X-Request-Id $request_id;），r.variables.request_id 每次返回相同的值。

变量在以下情况下可写：

  • 使用 js_var 指令（http 或 stream）创建（自 0.5.3）
  • 在 nginx 配置文件中被引用

即便如此，某些内嵌变量仍然无法被赋值（例如 $http_*）。

r.warn(string) ​

将字符串写入错误日志的 warning 级别。

注意：由于 nginx 有硬编码的最大行长度限制，仅可记录字符串的前 2048 字节。

Stream 会话对象（Stream Session） ​

Stream 会话对象仅在 ngx_stream_js_module 模块中可用。

在 0.8.5 版本之前，该对象的所有字符串属性均为字节字符串。

s.allow() ​

s.done(0) 的别名（0.2.4）。

s.decline() ​

s.done(-5) 的别名（0.2.4）。

s.deny() ​

s.done(403) 的别名（0.2.4）。

s.done([code]) ​

为当前阶段处理程序设置退出 code，默认值为 0。

实际的完成操作在 JS 处理程序完成且所有待处理事件（例如来自 ngx.fetch() 或 setTimeout() 的事件）处理完毕后发生（0.2.4）。

可能的 code 值：

  • 0 — 成功完成，将控制权传递给下一阶段
  • -5 — 未决定，将控制权传递给当前阶段的下一个处理程序（如果有）
  • 403 — 访问被禁止（js_access 或 js_preread）

s.error(string) ​

将字符串写入错误日志的 error 级别。

注意：由于 nginx 有硬编码的最大行长度限制，仅可记录字符串的前 2048 字节。

s.log(string) ​

将字符串写入错误日志的 info 级别。

注意：由于 nginx 有硬编码的最大行长度限制，仅可记录字符串的前 2048 字节。

s.off(eventName) ​

注销通过 s.on() 方法设置的回调（0.2.4）。

s.on(event, callback) ​

为指定事件注册回调（0.2.4）。

事件可以是以下字符串之一：

  • upload — 来自客户端的新数据（字符串）
  • download — 发送给客户端的新数据（字符串）
  • upstream — 来自客户端的新数据（Buffer）（自 0.5.0）
  • downstream — 发送给客户端的新数据（Buffer）（自 0.5.0）

完成回调的原型为：callback(data, flags)，其中：

  • data 为字符串或 Buffer（取决于事件类型）
  • flags 是一个包含以下属性的对象：
    • last — 布尔值，如果数据是最后一个缓冲区则为 true

s.remoteAddress ​

客户端地址，只读。

s.rawVariables ​

nginx 变量，以 Buffer 形式表示，可写（自 0.5.0）。

s.jsVarNames([prefix]) ​

返回一个包含通过 js_var 指令声明的 nginx 变量名称的新数组（自 0.9.9）。

可选的 prefix 参数必须为字符串。如果指定，则仅返回以该前缀开头的名称。

s.send(data[, options]) ​

将数据添加到数据块链中，这些数据块将沿正向转发：

  • 在 download 回调中：转发给客户端
  • 在 upload 回调中：转发给上游服务器

实际转发稍后发生，在当前链的所有数据块处理完成后。

数据可以是字符串或 Buffer（0.5.0）。

options 是一个对象，用于覆盖从传入数据块缓冲区派生的 nginx 缓冲区标志。

可覆盖的标志：

  • last（布尔值）— 如果缓冲区是最后一个缓冲区则为 true
  • flush（布尔值）— 如果缓冲区应设置 flush 标志则为 true

s.sendDownstream() ​

与 s.send() 相同，但始终将数据发送给客户端（自 0.7.8）。

s.sendUpstream() ​

与 s.send() 相同，但始终发送来自客户端的数据（自 0.7.8）。

s.status ​

会话状态码，$status 变量的别名，只读（自 0.5.2）。

s.setReturnValue(value) ​

设置 js_set 处理程序的返回值（0.7.0）。

与普通的 return 语句不同，当处理程序是 JS 异步函数时，应使用此方法。

例如：

js
async function js_set(r) {
    const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
    r.setReturnValue(digest);
}

s.variables{} ​

nginx 变量对象，可写（自 0.2.8）。

变量仅在 nginx 配置文件中被引用时才可写。即便如此，某些内嵌变量仍然无法被赋值。

s.warn(string) ​

将字符串写入错误日志的 warning 级别。

注意：由于 nginx 有硬编码的最大行长度限制，仅可记录字符串的前 2048 字节。

周期性会话对象（Periodic Session） ​

Periodic Session 对象作为 js_periodic 处理程序的第一个参数提供（适用于 http 和 stream，自 0.8.1）。

PeriodicSession.rawVariables{} ​

nginx 变量，以 Buffer 形式表示，可写。

PeriodicSession.variables{} ​

nginx 变量对象，可写。

Headers（Fetch API） ​

Headers 接口自 0.5.1 起可用。

可使用 Headers() 构造函数创建新的 Headers 对象（自 0.7.10）：

js
new Headers([init])
  • init — 包含用于预填充 Headers 对象的 HTTP 头的对象，可以是字符串、名称-值对数组或现有的 Headers 对象。

新的 Headers 对象具有以下属性和方法：

  • append() — 向 Headers 对象中的现有头追加新值，或添加不存在的头（自 0.7.10）
  • delete() — 从 Headers 对象中删除头（自 0.7.10）
  • get() — 返回包含指定名称所有头值的字符串，以逗号和空格分隔
  • getAll(name) — 返回包含指定名称所有头值的数组
  • forEach() — 对 Headers 对象中的每个键/值对执行一次提供的函数（自 0.7.10）
  • has() — 返回布尔值，指示是否存在指定名称的头
  • set() — 为 Headers 对象中的现有头设置新值，或添加不存在的头（自 0.7.10）

Request（Fetch API） ​

Request 接口自 0.7.10 起可用。

可使用 Request() 构造函数创建新的 Request 对象：

js
new Request(resource[, options])

创建一个 Request 对象，供后续传递给 ngx.fetch()。

  • resource — 可以是 URL 或现有的 Request 对象
  • options — 可选参数，应为包含以下键的对象：
    • body — 请求体，默认为空
    • headers — 响应头对象，包含用于预填充 Headers 对象的 HTTP 头，可以是字符串、名称-值对数组或现有的 Headers 对象
    • method — HTTP 方法，默认使用 GET 方法

新的 Request 对象具有以下属性和方法：

  • arrayBuffer() — 返回一个 Promise，解析为 ArrayBuffer
  • bodyUsed — 布尔值，如果请求体已被使用则为 true
  • cache — 包含请求的缓存模式
  • credentials — 包含请求的凭据，默认为 same-origin
  • headers — 与 Request 关联的只读 Headers 对象
  • json() — 返回一个 Promise，解析为将请求体解析为 JSON 的结果
  • method — 包含请求方法
  • mode — 包含请求的模式
  • text() — 返回一个 Promise，解析为请求体的字符串表示
  • url — 包含请求的 URL

Response（Fetch API） ​

Response 接口自 0.5.1 起可用。

可使用 Response() 构造函数创建新的 Response 对象（自 0.7.10）：

js
new Response([body[, options]])
  • body — 可选参数，可以是字符串或缓冲区，默认为 null
  • options — 可选参数，应为包含以下键的对象：
    • headers — 响应头对象，包含用于预填充 Headers 对象的 HTTP 头，可以是字符串、名称-值对数组或现有的 Headers 对象
    • status — 响应的状态码
    • statusText — 与状态码对应的状态消息

新的 Response 对象具有以下属性和方法：

  • arrayBuffer() — 读取 Response 流直至完成，返回一个 Promise，解析为 ArrayBuffer
  • bodyUsed — 布尔值，如果响应体已被读取则为 true
  • headers — 与 Response 关联的只读 Headers 对象
  • json() — 读取 Response 流直至完成，返回一个 Promise，解析为将响应体文本解析为 JSON 的结果
  • ok — 布尔值，如果响应成功（状态码在 200–299 之间）则为 true
  • redirected — 布尔值，如果响应是重定向的结果则为 true
  • status — 响应的状态码
  • statusText — 与状态码对应的状态消息
  • text() — 读取 Response 流直至完成，返回一个 Promise，解析为字符串
  • type — 响应的类型
  • url — 响应的 URL

ngx 全局对象 ​

ngx 全局对象自 0.5.0 起可用。

ngx.build ​

包含可选的 nginx 构建名称的字符串，对应于 configure 脚本的 --build=name 参数，默认为 ""（0.8.0）。

ngx.conf_file_path ​

包含当前 nginx 配置文件路径的字符串（0.8.0）。

ngx.conf_prefix ​

包含 nginx 配置前缀文件路径的字符串 — nginx 当前查找配置的目录（0.7.8）。

ngx.error_log_path ​

包含当前错误日志文件路径的字符串（0.8.0）。

ngx.fetch(resource, [options]) ​

发起请求以获取资源（0.5.1）。

resource 可以是 URL 或 Request 对象（0.7.10）。

返回一个 Promise，解析为 Response 对象。

自 0.7.0 起支持 https:// 协议，不处理重定向。

如果 URL 指定为域名，则使用解析器确定。

如果指定了 https:// 协议，应配置 js_fetch_trusted_certificate 指令以验证资源 HTTPS 服务器的身份。

options 参数应为包含以下键的对象：

  • body — 请求体，默认为空
  • buffer_size — 读取响应的缓冲区大小，默认为 4096
  • headers — 请求头对象
  • max_response_body_size — 响应体的最大字节数，默认为 32768
  • method — HTTP 方法，默认使用 GET 方法
  • verify — 启用或禁用 HTTPS 服务器证书验证，默认为 true（0.7.0）

示例：

js
let reply = await ngx.fetch('http://nginx.org/');
let body = await reply.text();
r.return(200, body);

ngx.log(level, message) ​

以指定的日志级别将消息写入错误日志。

level 参数指定日志级别之一，message 参数可以是字符串或 Buffer。

可指定的日志级别：

  • ngx.INFO
  • ngx.WARN
  • ngx.ERR

注意：由于 nginx 有硬编码的最大行长度限制，仅可记录字符串的前 2048 字节。

ngx.prefix ​

包含 nginx 前缀文件路径的字符串 — 存放服务器文件的目录（0.8.0）。

ngx.version ​

包含 nginx 版本的字符串，例如 1.25.0（0.8.0）。

ngx.version_number ​

包含 nginx 版本的数字，例如 1025000（0.8.0）。

ngx.worker_id ​

对应于 nginx 内部工作进程 ID 的数字，值在 0 和 worker_processes 指令指定的值之间（0.8.0）。

ngx.shared 全局对象 ​

ngx.shared 全局对象自 0.8.0 起可用。

SharedDict（共享字典） ​

共享字典对象自 0.8.0 起可用。

共享字典的名称、类型和大小通过 http 或 stream 中的 js_shared_dict_zone 指令设置。

SharedDict 对象具有以下属性和方法：

ngx.shared.SharedDict.add(key, value [, timeout]) ​

仅当键尚不存在时，在字典中设置指定 key 的 value。

  • key — 表示要添加的项的键的字符串
  • value — 要添加的项的值
  • timeout — 可选参数，以毫秒为单位，覆盖 http 或 stream 中 js_shared_dict_zone 指令的 timeout 参数（自 0.8.5）

返回 true（如果值已成功添加到 SharedDict 字典），false（如果键已存在于字典中）。

如果 SharedDict 字典中没有足够的空闲空间，则抛出 SharedMemoryError。如果值的类型与字典期望的类型不同，则抛出 TypeError。

ngx.shared.SharedDict.capacity ​

返回 SharedDict 字典的容量，对应于 http 或 stream 中 js_shared_dict_zone 指令的 size 参数。

ngx.shared.SharedDict.clear() ​

从 SharedDict 字典中删除所有项。

ngx.shared.SharedDict.delete(key) ​

从 SharedDict 字典中删除与指定 key 关联的项。

如果字典中的项存在且已被删除则返回 true，否则返回 false。

ngx.shared.SharedDict.freeSpace() ​

返回空闲页大小（以字节为单位）。如果大小为 0，SharedDict 字典在已占用页中有空间时仍将接受新值。

ngx.shared.SharedDict.get(key) ​

通过 key 检索项，返回与键关联的值，如果不存在则返回 undefined。

ngx.shared.SharedDict.has(key) ​

通过 key 搜索项，如果存在则返回 true，否则返回 false。

ngx.shared.SharedDict.incr(key, delta[, init, timeout]) ​

将与 key 关联的整数值增加 delta。

  • key — 字符串
  • delta — 增加或减少值的数字
  • init — 如果键不存在，则将项初始化为可选的 init 参数，默认为 0
  • timeout — 可选参数，以毫秒为单位，覆盖 http 或 stream 中 js_shared_dict_zone 指令的 timeout 参数（自 0.8.5）

如果未指定 timeout 参数，则保留现有的逐项 TTL（自 0.9.7）。在 0.9.7 版本之前，省略 timeout 会将条目过期时间重置为指令默认值。

返回新值。

如果 SharedDict 字典中没有足够的空闲空间，则抛出 SharedMemoryError。如果此字典不期望数字类型，则抛出 TypeError。

此方法仅在字典类型通过 http 或 stream 中 js_shared_dict_zone 指令的 type=number 参数声明时可用。

ngx.shared.SharedDict.items([maxCount]) ​

返回 SharedDict 字典的键值项数组（自 0.8.1）。

maxCount 参数设置要检索的最大项数，默认为 1024。

ngx.shared.SharedDict.keys([maxCount]) ​

返回 SharedDict 字典的键数组。

maxCount 参数设置要检索的最大键数，默认为 1024。

ngx.shared.SharedDict.name ​

返回 SharedDict 字典的名称，对应于 http 或 stream 中 js_shared_dict_zone 指令的 zone= 参数。

ngx.shared.SharedDict.pop(key) ​

从 SharedDict 字典中删除与指定 key 关联的项，返回与键关联的值，如果不存在则返回 undefined。

ngx.shared.SharedDict.replace(key, value) ​

仅当键已存在时，为指定 key 替换 value。

如果值已成功替换则返回 true，如果键不存在于 SharedDict 字典中则返回 false。

如果 SharedDict 字典中没有足够的空闲空间，则抛出 SharedMemoryError。如果值的类型与字典期望的类型不同，则抛出 TypeError。

ngx.shared.SharedDict.set(key, value [, timeout]) ​

为指定 key 设置 value，返回此 SharedDict 字典（用于方法链）。

timeout 可选参数以毫秒为单位，覆盖 http 或 stream 中 js_shared_dict_zone 指令的 timeout 参数（自 0.8.5）。

ngx.shared.SharedDict.size() ​

返回 SharedDict 字典的项数。

ngx.shared.SharedDict.ttl(key) ​

返回指定 key 的剩余生存时间（以毫秒为单位），如果键不存在或已过期则返回 undefined（自 0.9.7）。

如果字典未通过 http 或 stream 中 js_shared_dict_zone 指令的 timeout 参数声明，则抛出 TypeError。

ngx.shared.SharedDict.type ​

返回 string 或 number，对应于 http 或 stream 中 js_shared_dict_zone 指令的 type= 参数设置的 SharedDict 字典类型。

内置对象 ​

console ​

console 对象在 nginx 中自 0.8.2 起可用，在 CLI 中自 0.2.6 起可用。

  • console.error(msg[, msg2 ...]) — 输出一条或多条错误消息。消息可以是字符串或对象。
  • console.info(msg[, msg2 ...]) — 输出一条或多条信息消息。消息可以是字符串或对象。
  • console.log(msg[, msg2 ...]) — 输出一条或多条日志消息。消息可以是字符串或对象。
  • console.time(label) — 启动一个计时器，用于跟踪操作耗时。label 参数允许命名不同的计时器。
  • console.timeEnd(label) — 停止由 console.time() 启动的计时器。label 参数允许命名不同的计时器。
  • console.warn(msg[, msg2 ...]) — 输出一条或多条警告消息。消息可以是字符串或对象。

crypto ​

crypto 对象是一个全局对象，允许使用加密功能（自 0.x 版本）。

注意：本文档基于 nginx 官方文档翻译，完整内容请参见 https://nginx.org/en/docs/njs/reference.html。由于原文档内容较长，部分模块（如 querystring、fs、xml、zlib 等）的详细说明请查阅官方文档。