Nginx网关指南：利用Njs脚本处理轻量级HTTP请求逻辑-Nginx-PHP中文网

Nginx + njs 是省资源又灵活的轻量HTTP逻辑处理方案，适用于鉴权前置、请求改写、灰度路由等场景；njs因官方内置、沙箱安全、语法亲和、上下文丰富而优于Lua和rewrite指令。

nginx网关指南：利用njs脚本处理轻量级http请求逻辑

用 Nginx + njs 处理轻量 HTTP 逻辑，是比写后端服务更省资源、比纯配置更灵活的折中方案。它适合鉴权前置、请求改写、灰度路由、简单聚合等场景，不碰复杂业务，但能挡掉大量无效流量或标准化入口行为。

为什么选 njs 而不是 Lua 或 rewrite 指令

njs 是 Nginx 官方维护的嵌入式 JavaScript 引擎，轻量、安全、与配置深度集成。相比 OpenResty 的 Lua：

njs 默认启用，无需额外编译或模块安装（Nginx 1.19.5+ 内置）
运行在受限沙箱中，不能访问文件系统、网络或执行系统命令，天然防误操作
语法接近标准 JS（ES5 主体 + 部分 ES6），前端同学上手快，调试也方便
rewrite 指令只能做静态字符串替换，无法读取请求头、判断参数、调用时间函数等；njs 可以读取 $r.headersIn、$r.args、$r.remoteAddress 等上下文变量

一个真实可用的鉴权透传示例

比如要求所有 /api/ 路径必须带有效的 X-Api-Key，且只允许内网调用，否则返回 403：

# nginx.conf
js_import conf.d/auth.js;
server {
    location /api/ {
        js_filter auth.checkApiKey;
        proxy_pass http://backend;
    }
}

对应 conf.d/auth.js：

function checkApiKey(r) {
    const key = r.headersIn['X-Api-Key'];
    const ip = r.remoteAddress;
<pre class="brush:php;toolbar:false;">if (!key || key !== 'prod-secret-2024') {
    r.return(403, 'Invalid or missing API key\n');
    return;
}

if (!ip.startsWith('10.') && !ip.startsWith('192.168.')) {
    r.return(403, 'API access restricted to internal network\n');
    return;
}

// 继续转发
r.internalRedirect('/proxy' + r.uri);

}

export default { checkApiKey };

注意：js_filter 在请求进入 location 前执行，可中断流程；js_content 用于完全由 JS 生成响应；js_set 适合变量赋值（如生成 trace-id）。

常见陷阱与最佳实践

njs 看似简单，但几个细节容易踩坑：

变量作用域是函数级，不要在顶层声明状态变量（如计数器），每次请求都是全新上下文
异步操作（如 fetch）目前仅支持 experimental 版本，生产环境建议避免；同步逻辑务必控制在毫秒级，否则阻塞 worker 进程
日志用 r.warn() 或 r.error()，别用 console.log —— 它不会输出到 error_log
修改请求头要用 r.headersIn 读，但写入上游要用 r.headersOut 或 proxy_set_header 配合；njs 本身不能直接改写发往 upstream 的 header
脚本变更后需 reload Nginx（nginx -s reload），njs 不支持热重载