OpenResty 配置参数详解（nginx.conf 与 Lua 指令）

OpenResty 1.31.1.1 配置参数详解：nginx.conf 全局/http/server 结构、content_by_lua_block、LuaJIT、lualib 与 resty 库、常用 Lua 指令与生产模板，全部基于实测

OpenRestyOpenRestyWeb 服务器与反向代理2026/10/08

OpenResty 配置参数详解（nginx.conf 与 Lua 指令）

目标：详解 OpenResty 1.31.1.1 的配置体系。OpenResty 使用 Nginx 配置语法，并扩展了一批 Lua 指令（content_by_lua_block 等）；本文档基于实测解析主配置结构与常用 Lua 指令。

环境信息

  • OpenResty 内核版本：openresty/1.31.1.1
  • LuaJIT：LuaJIT 2.1.ROLLING
  • 主配置：/usr/local/openresty/nginx/conf/nginx.conf
  • Lua 库目录：/usr/local/openresty/lualib/
  • 工具目录：/usr/local/openresty/bin/

前置条件

  • 已按《Ubuntu 22.04 安装 OpenResty 指南》完成安装
  • 掌握基础 Nginx 语法

参数查看与修改方式

  • 查看编译参数：openresty -V
  • 查看版本：openresty -v
  • 测试配置：openresty -t
  • 修改配置：编辑 nginx.conf 后 openresty -s reload
  • 查看 Lua 库：ls /usr/local/openresty/lualib/

参数总览

OpenResty 配置 = Nginx 标准配置 + Lua 扩展指令：

层级指令示例作用
全局worker_processes, events进程与事件模型
httphttp { ... }, lua_package_path全局 HTTP 与 Lua 路径
serverlisten, server_name, location站点与路由
locationcontent_by_lua_block, rewrite_by_lua_blockLua 处理逻辑

一、全局与事件配置

worker_processes 1;                # 工作进程数
events {
    worker_connections 1024;        # 单进程最大连接数
}

二、http 块与 Lua 路径

http {
    include mime.types;
    default_type application/octet-stream;
    sendfile on;
    lua_package_path '/usr/local/openresty/lualib/?.lua;;';  # Lua 模块搜索路径
    server { ... }
}

💡 说明：lua_package_path 决定 require 从哪些路径加载 Lua 库；;; 表示追加默认路径。

三、content_by_lua_block —— Lua 响应

location / {
    default_type text/plain;
    content_by_lua_block {
        ngx.say("Hello OpenResty, host=" .. ngx.var.http_host)
    }
}

对应实测回显（访问 /）：

Hello OpenResty, host=127.0.0.1:28080
常用 ngx API作用
ngx.say(...)发送响应体并结束
ngx.print(...)发送响应体（不结束）
ngx.var.xxx读写 Nginx 变量（如 ngx.var.http_host）
ngx.header.xxx设置响应头
ngx.status设置/获取状态码

四、Lua 指令族

OpenResty 在不同处理阶段提供 Lua 指令：

指令阶段用途
init_by_lua_block启动全局初始化（变量/连接池）
rewrite_by_lua_block重写URI 改写、鉴权
access_by_lua_block访问控制限流、权限
content_by_lua_block内容生成生成响应
log_by_lua_block日志记录自定义日志
header_filter_by_lua_block响应头过滤改写响应头

五、Lua 工具库（lualib）

实测 ls /usr/local/openresty/lualib/ 输出：

cjson.so        # JSON 编解码
librestysignal.so
ngx/            # Nginx Lua 扩展
redis/          # Redis 客户端
resty/          # 常用 resty 库（core、http 等）
tablepool.lua

常见 resty.* 模块：

模块用途
resty.core核心 API 扩展
resty.request请求对象
resty.httpHTTP 客户端（需额外安装 lua-resty-http）
cjsonJSON 序列化/反序列化

六、resty 与 opm 工具

  • resty：命令行运行 Lua 脚本（实测在 Alpine 容器内因缺 perl 报错，完整系统正常），用于本地调试 resty -e 'print(1+1)'。
  • opm：OpenResty 包管理器，安装第三方 resty 库：opm get ledgetech/lua-resty-http。

七、LuaJIT 说明

luajit -v

实测回显：

LuaJIT 2.1.ROLLING -- Copyright (C) 2005-2026 Mike Pall. https://luajit.org/

LuaJIT 兼容 Lua 5.1 语法并扩展 FFI，性能优于标准 Lua。

生产配置模板

适用场景：8GB 内存、Lua API 网关/反向代理。

worker_processes auto;
events { worker_connections 2048; }
http {
    include mime.types;
    default_type application/octet-stream;
    sendfile on;
    lua_package_path '/usr/local/openresty/lualib/?.lua;;';
    lua_shared_dict rate_limit 10m;      # 共享内存（限流/计数）
    upstream api_backend { server 127.0.0.1:9000; }
    server {
        listen 80;
        server_name api.example.com;
        access_by_lua_block {
            local limit = ngx.shared.rate_limit
            local key = ngx.var.binary_remote_addr
            local n = limit:incr(key, 1)
            if n == 1 then limit:expire(key, 60) end
            if n > 100 then
                ngx.status = 429
                ngx.say("rate limited")
                return ngx.exit(429)
            end
        }
        location /api/ {
            proxy_pass http://api_backend;
            proxy_set_header Host $host;
        }
    }
}

常见问题

Q1：content_by_lua_block unknown directive A：确认运行的是 OpenResty 内核（openresty -v 显示 openresty 前缀），原版 nginx 无此指令。

Q2：require("cjson") 失败 A：确认 lua_package_path 包含 lualib/?.lua 和 lualib/?/init.lua，且模块已装在 /usr/local/openresty/lualib/。

Q3：reload 后配置不生效 A：openresty -t 校验通过后再 reload；Lua 配置有语法错误时 openresty -t 会拦截。

Q4：内存共享 lua_shared_dict 不够 A：首次分配后无法扩容，需修改 lua_shared_dict xx 10m 大小并 reload；过小则 incr 返回 nil 并打告警日志。

参考链接