在宝塔 Nginx 上安装与配置 lua-cjson 教程

适用环境 ：Ubuntu + 宝塔面板 + Nginx + Lua 模块
目标：让 Nginx 的 Lua 脚本能成功 require("cjson")，避免因缺少 JSON 解析库导致的 500 错误

🧩 一、为什么需要 lua-cjson？

在使用 Nginx + Lua 开发 API 网关、鉴权逻辑或动态路由时，经常需要处理 JSON 数据。而标准 Lua 并不自带 JSON 库，lua-cjson 是一个高性能的 C 扩展库，能高效地进行 JSON 编码/解码。

但宝塔面板默认并未集成 lua-cjson，需手动编译安装。

🔧 二、安装 LuaJIT 开发环境

首先确保系统已安装 LuaJIT 及其开发头文件：

bash 复制代码

sudo apt update
sudo apt install luajit libluajit-5.1-dev -y

验证安装是否成功：

bash 复制代码

luajit -v

正常输出类似：

复制代码

LuaJIT 2.1.0-beta3 -- Copyright (C) 2005-2017 Mike Pall. https://luajit.org/

确认头文件路径（后续编译需要）：

bash 复制代码

find /usr -name lua.h

常见路径为：

复制代码

/usr/include/luajit-2.1/lua.h

⚠️ 注意：不要使用 /usr/local/include/...，除非你手动编译过 LuaJIT。宝塔通常依赖系统包管理器安装的版本。

📦 三、下载并编译 lua-cjson

进入源码目录，克隆官方仓库（推荐 OpenResty 维护版）：

bash 复制代码

cd /usr/local/src
git clone https://github.com/openresty/lua-cjson.git
cd lua-cjson

✅ 正确编译命令（关键！）

由于宝塔 Nginx 使用的是 LuaJIT，必须指定正确的 include 路径：

bash 复制代码

make clean
make LUAJIT=1 LUA_INCLUDE_DIR=/usr/include/luajit-2.1

如果遇到编译错误（如找不到 lua.h），可强制指定 CFLAGS：

bash 复制代码

make clean
make LUAJIT=1 LUA_INCLUDE_DIR=/usr/include/luajit-2.1 \
  CFLAGS="-O3 -Wall -fpic -I/usr/include/luajit-2.1"

✅ 成功后会生成 cjson.so 文件：

bash 复制代码

ls -l cjson.so

🗂️ 四、拷贝 so 文件到 Nginx Lua 模块目录

宝塔面板中，Nginx 的 Lua 模块默认路径为：

复制代码

/www/server/nginx/lib/lua/

执行拷贝：

bash 复制代码

cp cjson.so /www/server/nginx/lib/lua/

💡 如果存在子目录 5.1/（部分版本有），也建议复制一份：
bash 复制代码
cp cjson.so /www/server/nginx/lib/lua/5.1/

⚙️ 五、配置 Nginx 的 Lua 路径

编辑 Nginx 主配置文件：

bash 复制代码

nano /www/server/nginx/conf/nginx.conf

在 http { } 块内添加以下两行（通常放在最顶部）：

nginx 复制代码

lua_package_path "/www/server/nginx/lib/lua/?.lua;;";
lua_package_cpath "/www/server/nginx/lib/lua/?.so;;";

✅ 说明：

lua_package_path：用于 .lua 脚本

lua_package_cpath：用于 .so 动态库（如 cjson.so）

自动添加命令（可选）

如果你不想手动编辑，可用 sed 命令自动插入：

bash 复制代码

# 先确保已有 lua_package_path（宝塔通常已有）
# 若没有，先手动加一行 lua_package_path ...
sudo sed -i '/lua_package_path/a\    lua_package_cpath "/www/server/nginx/lib/lua/?.so;;";' /www/server/nginx/conf/nginx.conf

🔄 六、重启 Nginx 生效

先测试配置是否正确：

bash 复制代码

nginx -t

无报错后重启：

bash 复制代码

systemctl restart nginx

或通过 宝塔面板 → 软件商店 → Nginx → 重载配置

🧪 七、测试 lua-cjson 是否可用

临时在某个 server 块中添加测试接口：

nginx 复制代码

location /test_cjson {
    default_type text/plain;
    content_by_lua_block {
        local ok, cjson = pcall(require, "cjson")
        if ok then
            ngx.say("✅ cjson OK")
        else
            ngx.say("❌ cjson NOT FOUND: ", cjson)
        end
    }
}

保存后重载 Nginx，然后访问：

bash 复制代码

curl http://127.0.0.1/test_cjson

✅ 正常输出：

复制代码

✅ cjson OK

如果返回 "NOT FOUND"，请检查：

cjson.so 是否在正确目录

lua_package_cpath 路径是否匹配

Nginx 是否使用 LuaJIT（而非标准 Lua）

✅ 八、总结

步骤	操作
1️⃣	安装 `luajit` 和 `libluajit-5.1-dev`
2️⃣	从 GitHub 克隆 `lua-cjson` 并指定 `LUA_INCLUDE_DIR` 编译
3️⃣	将生成的 `cjson.so` 复制到 `/www/server/nginx/lib/lua/`
4️⃣	在 `nginx.conf` 中配置 `lua_package_cpath`
5️⃣	重载 Nginx 并测试

完成以上步骤后，你的 Nginx Lua 脚本即可安全使用：

lua 复制代码

local cjson = require "cjson"
local data = cjson.decode('{"name":"Qwen"}')
ngx.say(cjson.encode(data))

再也不用担心因缺少 JSON 库而返回 500 错误啦！

📌 温馨提示 ：

若你使用的是 OpenResty 或 自编译 Nginx + Lua ，路径可能不同，请根据实际环境调整。

宝塔用户请勿随意升级 Nginx，否则可能丢失自定义模块！