nginx的JavaScript魔力：njs简介与实践
Nginx 的 JavaScript 魔力：njs 简介与实践（2026 年视角）
njs（NGINX JavaScript module）是 NGINX 官方推出的动态模块，让你可以用JavaScript（ECMAScript 5.1 严格模式 + 部分 ES6+ 扩展）直接在 NGINX 内部编写逻辑，而无需编写 C 模块或依赖 Lua/OpenResty。
它极大提升了 NGINX 的可编程性，尤其适合：
- 复杂的访问控制、请求/响应头修改
- 轻量级 API 网关、认证、A/B 测试
- 子请求、异步内容生成、响应过滤
- 与现代 JS 生态（如 QuickJS 引擎）结合
2026 年最新版本（njs 0.9.5，2026年1月发布）已支持QuickJS 引擎（完整 ES2023 兼容，包括模块、async generators、proxies、BigInt 等），性能提升显著（0.9.0 版本引擎性能提升 30%），Fetch API、WebCrypto、XML/Zlib 等模块更完善。
一、njs 的核心优势（对比 Lua/OpenResty）
| 项目 | njs (NGINX 官方) | OpenResty (Lua) | 选择建议（2026） |
|---|---|---|---|
| 语言 | JavaScript (ES5+ 部分 ES2023) | Lua | 团队熟悉 JS 首选 njs |
| 引擎 | QuickJS / 原生 njs（可选） | LuaJIT | QuickJS 更现代 |
| 模块加载 | 动态模块（无需重编译 NGINX） | 需要 OpenResty 发行版 | njs 更轻便 |
| 官方支持 | NGINX 官方维护 | 第三方 | 稳定性更高 |
| 生态 | Fetch、Crypto、XML、Zlib、共享字典 | 更丰富 Lua 库 | njs 够用且轻量 |
| 性能 | 高（QuickJS 优化后接近原生） | 极高（LuaJIT） | 日常场景差距小 |
| 学习曲线 | 低（前端/全栈开发友好） | 中（Lua 语法不同） | JS 开发者选 njs |
一句话总结：如果你团队偏好 JavaScript，想在原生 NGINX 上加“胶水”逻辑，而不是完整 API 网关，njs 是 2026 年最优雅的选择。
二、快速上手（安装 & Hello World）
1. 安装 njs（主流方式）
Debian/Ubuntu（官方仓库）：
# 添加 NGINX 官方源（假设已加）aptinstallnginx-module-njsDocker（最推荐测试）：
dockerrun -it --rm -p8080:80 nginx:1.27 njs -V# 检查版本# 或使用带 njs 的镜像dockerrun -p8080:80 -v$(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro nginxinc/nginx-unprivileged:1.27-njs从源码（支持 QuickJS）：
参考 https://nginx.org/en/docs/njs/install.html
2. 最简单 Hello World
创建http.js：
functionhello(r){r.return(200,"Hello from njs! 🌟\n");}exportdefault{hello};nginx.conf 配置：
load_module modules/ngx_http_js_module.so; # 或 .dll http { js_import main from /etc/nginx/njs/http.js; # 路径根据实际情况 server { listen 80; location /hello { js_content main.hello; # 调用函数 } } }重载 NGINX：
nginx -s reloadcurlhttp://localhost/hello# 输出：Hello from njs! 🌟三、2026 年常用 njs 能力 & 实战示例
1. 请求头/响应头操作（最常见）
functionaddSecurityHeaders(r){r.headersOut['X-Content-Type-Options']='nosniff';r.headersOut['X-Frame-Options']='DENY';r.headersOut['Strict-Transport-Security']='max-age=31536000; includeSubDomains';r.return(200);}functionlogRequest(r){r.log(`Request from${r.remoteAddress}to${r.uri}`);}2. 简单 API 网关 + 认证（Token 校验）
asyncfunctionauthGateway(r){consttoken=r.headersIn['Authorization']||'';if(!token.startsWith('Bearer ')){r.return(401,'Missing or invalid token');return;}constcleanToken=token.slice(7);try{// 假设调用外部 auth 服务（njs 支持 async/await + fetch）constresp=awaitngx.fetch('https://auth.example.com/verify',{method:'POST',headers:{'Authorization':`Bearer${cleanToken}`}});if(resp.status!==200){r.return(403,'Forbidden');return;}// 透传上游r.subrequest('/upstream'+r.uri,{method:r.method});}catch(e){r.return(500,'Internal auth error');}}配置：
location /api/ { js_content main.authGateway; proxy_pass http://backend; }3. 响应体过滤（替换内容）
functionreplaceText(r){r.sendHeader();r.on('upload',(data)=>{// 简单字符串替换（生产慎用，性能考虑）constmodified=data.replace(/old-brand/g,'new-brand');r.send(modified);});r.finish();}4. 定时任务（js_periodic，新功能）
http { js_periodic main.cleanup interval=300s; # 每5分钟执行一次 } # http.js function cleanup() { // 清理共享字典、日志等 ngx.shared.my_cache.clear?.(); }5. 共享字典 + 状态保持（rate limit 示例）
http { js_shared_dict_zone zone=rate_limit:1m; location /limited { js_content main.rateLimit; } }functionrateLimit(r){constkey=r.remoteAddress;constlimit=100;// 每分钟100次constdict=ngx.shared.rate_limit;letcount=dict.get(key)||0;count=parseInt(count)+1;if(count>limit){r.return(429,'Too Many Requests');return;}dict.set(key,count,60);// 60秒过期r.return(200,`OK, count:${count}`);}四、njs 2026 年最新亮点（0.9.x 系列）
- *QuickJS 引擎*（ES2023 完整支持）：async generators、Proxy、BigInt、模块语法
- ngx.fetch()增强：HTTP forward proxy、keepalive 支持
- js_periodic：定时 JS 执行（http/stream 均支持）
- 共享字典持久化：state file 支持
- 性能：0.9.0 引擎提升 30%，QuickJS 模式更现代
官方示例仓库（强烈推荐克隆）：https://github.com/nginx/njs-examples
五、注意事项 & 最佳实践（2026 生产建议）
- 性能：njs 轻量但非 JIT，避免复杂计算放 JS 中
- 调试：用
njsCLI 交互式调试（docker run nginx njs）dockerrun -it nginx njs>>r={uri:'/test'};hello(r) - 模块化：用
export default { fn1, fn2 }组织代码 - 安全：不要在 njs 中处理敏感逻辑（密钥等），优先 upstream
- 兼容：QuickJS 模式下 ES2023 语法可用，但旧 njs 引擎仍为 ES5+ 兼容
- 监控：用 NGINX stub_status 或 Prometheus exporter 监控 JS 执行耗时
njs 让 NGINX 从“高性能反代”进化成“可编程边缘计算节点”，是 2026 年构建轻量 API 网关、零信任入口、动态路由的利器。
如果你想深入某个场景（如完整 API 网关、JWT 校验、WAF 规则引擎、A/B 测试），贴出需求，我可以直接给出更详细的 njs 代码 + 配置。