简介面向Lua开发者的JSON处理库lua-cjson-2.1.0已编译版本可直接在支持平台上加载使用省去源码编译环节。该库采用C实现解析与生成JSON字符串速度快适合游戏开发、Web接口联调、配置文件读写等需要高频处理数据的场景。压缩包共50个文件包含cjson.dll/so动态链接库、头文件、Lua示例脚本、C源码、CMakeLists与编译脚本以及README、LICENSE等文档整体仅239KB轻量易集成。其中json和lua文件可用于测试与演示h/c文件便于二次开发时查看实现细节dll文件则支持require(cjson)直接调用。已有987人学习下载对希望快速接入JSON能力的Lua开发者而言这份预编译包提供了即取即用的完整组件同时保留源码与构建配置方便在不同环境下自行调整。 做后端开发这几年只要项目里碰过 Lua十有八九都绕不开 lua-cjson 这个库。它不是什么花哨的框架就是 Lua 世界里最常用的 JSON 编解码 C 扩展OpenResty 内部集成过很多网关、WAF、游戏服务器的战斗逻辑也都在用。最近我要在纯 LuaJIT 环境里处理一批第三方接口的 JSON 数据又不想改系统全局的 Lua 环境翻出来这份 lua-cjson-2.1.0-已编译的产物干脆把整个接入和排坑过程整理出来。这篇东西不是文档复读是我自己动手编译、装载、压测之后的一些实操经验适合正在折腾 lua-cjson 2.1.0、或者拿到别人编译好的 cjson.so 不知道怎么用的人参考。1. 为什么偏偏是 lua-cjson核心价值与适用场景1.1 JSON 在 Lua 生态里的地位Lua 语言本身非常克制标准库里没有 JSON 编解码能力这和 Python 那种自带 json 模块的设计思路完全不同。但现实项目里无论是和 HTTP API 交互、读写配置文件还是做 Redis 消息序列化JSON 几乎是无处不在的基础格式。这时候就需要一个高性能、稳定、和 Lua 配合紧密的 C 扩展来补上这个缺口。lua-cjson 就是这个生态位上的头号选手。它是 Mark Pulford 写的纯 C 实现底层不依赖任何第三方 JSON 库解析和序列化一条龙。2.1.0 版本在安全性和 UTF-8 处理上做了不少加强专门处理了解析超大数字、空数组、嵌套深结构这些历史遗留问题整体行为比老版本更可控。1.2 为什么强调“已编译”这个状态很多人初学 Lua 扩展时第一个拦路虎不是写代码而是编译。lua-cjson 编译本身不复杂一个 Makefile 就搞定但前提是你的机器上得有匹配的 Lua 头文件、编译器环境、sysroot 都得对得上。更重要的是Lua 版本不同lua_State 结构体内部布局和 API 宏定义都有差异你用 Lua 5.1 的头编译出来的 .so放到 LuaJIT 的环境里可能能跑但放到 Lua 5.4 的环境里就可能直接段错误。“已编译”三个字在这种语境下意味着源码包已经从 GitHub 拉下来、Makefile 执行完毕、cjson.so 文件已经躺在了目录里。你省掉了拉取源码、处理 include 路径、解决链接错误这些步骤直接进入“部署验证”阶段。但这里我要泼一盆冷水拿到已编译产物不代表万事大吉你把 .so 丢进系统后必须要先验证 Lua 的 ABI 兼容性否则运行期崩溃会让你排查到怀疑人生这一点后面我会详细说。2. 接入前的环境核对与装载方案2.1 先确认自己的 Lua 运行时很多人拿到 cjson.so 就直接 require(cjson)然后报错就慌。实际上你应该先花三十秒确认当前 Lua 运行时是什么是标准 Lua 5.1/5.2/5.4还是 LuaJIT可以用lua -v或luajit -v查看。这决定了 cjson 能否直接加载成功因为 lua-cjson 在编译期会通过LUA_VERSION_NUM宏来适配 API不同大版本之间编译出来的二进制不通用。# 检查系统 Lua 版本 lua -v Lua 5.1.5 Copyright (C) 1994-2012 Lua.org, PUC-Rio # 或者如果是 LuaJIT luajit -v LuaJIT 2.1.0-beta3 -- Copyright (C) 2005-2017 Mike Pall如果你发现手头这份已编译的 cjson.so 和系统 Lua 版本不匹配不要灰心往下看第 4 节我会教你从源码重新编译一套属于自己的 cjson.so这个过程完全可控。2.2 动态库装载路径与 package.cpathLua 加载 C 扩展的机制很有意思它不走package.path而是走package.cpath这个变量决定了 .so 文件要去哪里找。默认情况下很多发行版只配置了系统目录比如/usr/local/lib/lua/5.1/?.so如果你的 cjson.so 放在/opt/mylua/lib/直接 require 肯定找不到。实测下来最稳妥的做法是在启动脚本里显式把目录加进去不要污染系统级配置尤其是多项目共存的服务器上。-- 在 main.lua 开头设置 package.cpath package.cpath .. ;/opt/mylua/lib/?.so;/opt/mylua/lib/lua/5.1/?.so local cjson require(cjson) assert(cjson, cjson 加载失败)这里有个细节?.so中问号会被 Lua 替换成 require 的名字。比如你require(cjson.safe)它就会去找cjson/safe.so。lua-cjson 2.1.0 其实带了两个核心模块一个是普通版本cjson一个是安全版本cjson.safe。普通版本在解析非法 JSON 时会直接抛出错误而 safe 版本会把错误包装成一个 table 返回这样可以避免 pcall 的层层包裹。2.3 加载测试与 ABI 冒烟验证拿到 .so 文件先别急着写业务逻辑先跑一个冒烟测试确认二进制和运行时兼容性。我见过有人把 Lua 5.3 编出来的 cjson.so 放到 LuaJIT 下强行使用结果解析正常编码也正常但偶发崩溃这种问题最阴间。-- smoke.lua package.cpath package.cpath .. ;/opt/mylua/lib/?.so local cjson require(cjson) local ok, obj pcall(cjson.decode, {name:test,items:[1,2,3],ok:true}) if not ok then error(cjson decode failed: .. tostring(obj)) end assert(obj.name test, field name mismatch) assert(#obj.items 3, array length mismatch) assert(obj.ok true, boolean mismatch) local encoded cjson.encode({a 1, b {c x}}) assert(encoded {a:1,b:{c:x}}, encode mismatch) print(smoke test passed)如果这步通过了说明 .so 和运行时基本吻合。如果 pass 不了别硬调直接看第 4 节重新编译一份最省事。3. 已编译产物在项目中的落地实践3.1 按项目隔离依赖目录既然都已经拿到已编译的 cjson.so说明你不想在中间环节再折腾。我的建议是目录要隔离别直接扔进/usr/lib64/lua/。把 cjson.so 放到项目自身的lib/目录下和纯 Lua 代码放在一起这样部署时整个目录拷走目标机器上什么都不用装。比如我的一个网关项目结构就是这样的/opt/gateway/ ├── lib/ │ ├── cjson.so # lua-cjson 2.1.0 已编译产物 │ └── resty/ ├── lua/ │ ├── main.lua │ └── handler.lua └── bin/ └── start.sh这样最大的好处是版本可控。系统里某个项目要升 cjson 2.1.1我这边 2.1.0 完全不受影响。做线上服务的人都有体会依赖隔离是保平安的底线。3.2 与 OpenResty / LuaJIT 环境配合的注意点如果你的运行环境是 OpenResty那要特别小心。OpenResty 自带了一份 lua-cjson而且版本可能和你这份 2.1.0 不一样。默认情况下require(cjson)会加载 OpenResty 内置的那个你手动指定 package.cpath 覆盖也行但我不建议在 OpenResty 环境里强行替换系统内置的 cjson。为什么因为 OpenResty 对 cjson 打了自己的补丁比如增加了一些内部缓存优化你要是强行覆盖可能出现 API 行为不一致尤其是cjson.encode对空 table 编码成[]还是{}的处理规则不同版本之间有微妙差异这类问题排查起来非常痛苦。如果是纯 LuaJIT 环境问题不大直接把 cjson.so 放进目录即可。但在用之前最好确认 LuaJIT 是用-DLUAJIT_ENABLE_LUA52COMPAT编译的因为这种编译选项会影响部分 API 语义cjson 通过常规 Lua C API 也能跑但部分字符串处理路径在不同兼容级别下的表现不完全一致实测下来最好全链路做一遍烟雾测试。3.3 环境变量 vs 代码内配置我见过不少项目习惯用LUA_CPATH环境变量来做动态库路径。这招在本地开发时很快但上了容器或者 systemd 服务之后环境变量经常会被改写或遗漏导致启动时报module cjson not found。所以我的建议是在入口代码里显式写 package.cpath不要依赖环境变量。或者两者都配代码里作为兜底。这看起来有点土但确实最不容易出问题运维投拆少一半。4. 从头编译一份自己的 lua-cjson 2.1.04.1 编译准备与参数说明如果你不想继续用别人的已编译产物或者拿到的那份和本机环境不兼容我们从头编一遍。整个过程也就几十秒核心是搞懂 Makefile 里的几个参数。先从 GitHub 拉源码注意 2.1.0 的 release 分支。git clone https://github.com/mpx/lua-cjson.git cd lua-cjson git checkout 2.1.0lua-cjson 的 Makefile 支持几个关键变量LUA_INCLUDE_DIR、LUA_LIBDIR、LUA_VERSION_NUM。这三个直接影响编译产物是否能匹配目标运行时。# 对标准 Lua 5.1 的典型编译 make LUA_INCLUDE_DIR/usr/include/lua5.1 \ LUA_LIBDIR/usr/lib/x86_64-linux-gnu/lua/5.1 \ LUA_VERSION_NUM501 # 对 LuaJIT 2.1 的典型编译 make LUA_INCLUDE_DIR/usr/include/luajit-2.1 \ LUA_LIBDIR/usr/lib/x86_64-linux-gnu/lua/5.1 \ LUA_VERSION_NUM501这里要解释一个很多人困惑的点LuaJIT 的 ABI 兼容的是 Lua 5.1所以 LUA_VERSION_NUM 还是填 501不要填 502 或 504。cjson 源码里用LUA_VERSION_NUM来判断怎么调用 API比如在 Lua 5.2 以后lua_objlen改名成lua_rawlen如果这个宏定义错了编译出来轻则警告重则直接加载失败甚至运行期内存错乱。4.2 编译过程与 CFLAGS 调优lua-cjson 在 2.1.0 相对老版本增加了对 UTF-8 的默认处理默认情况不校验如果你想要更严格的 UTF-8 检查可以打开编码检查宏。我一般不会开因为绝大多数内部 JSON 数据不需要那么严格开了反而降低吞吐。直接编译make LUA_INCLUDE_DIR/usr/include/luajit-2.1 \ LUA_LIBDIR/usr/lib/x86_64-linux-gnu/lua/5.1 \ LUA_VERSION_NUM501编译完成后目录下会生成 cjson.so。你可以用strip把符号表去掉体积缩小大约三分之一加载速度也能快一点。不过带符号版本对线上问题排查更有价值进退取舍看项目。# 可选缩小文件体积 strip cjson.so如果你编译时报找不到lua.h说明 LUA_INCLUDE_DIR 路径不对。先确认头文件位置find /usr -name lua.h 2/dev/null4.3 安装到了系统要不要更新缓存lua-cjson 是纯 C 动态库没有 LuaRocks 那种 module cache 机制只要 .so 文件在磁盘上放对位置即可。放到系统目录如/usr/lib/x86_64-linux-gnu/lua/5.1/时不需要执行ldconfig因为 Lua 不通过 ld.so 缓存查找普通模块它是直接用 dlopen 按文件名拼路径加载的。真正容易出问题的反而是“目录放对了但权限不够”。如果你用非 root 账号跑 Lua而 .so 权限是 700 且 owner 是 root那也会导致加载失败注意一定要给到 755 或 644。5. 从 JSON 精度到稀疏数组的实战配置5.1 数字精度处理lua-cjson 2.1.0 有一个从引入开始就被反复讨论的特性默认情况下cjson.decode会把大整数转成 double导致精度丢失。如果你的接口返回身份证号、雪花ID超过 2^53直接 decode 出来数字会变样。实测这个场景下推荐用cjson.decode_array_with_array_mt或者配合cjson.set_number_type来规避。lua-cjson 2.1.0 允许你把整数保留成 64 位整数类型local cjson require(cjson) cjson.encode_number_precision(14) -- 默认精度其实是14可根据需要调 -- 如果你明确知道有大整数建议把数字格式设为 int cjson.set_number_type(cjson.INT)但要注意把数字类型全改成 INT 后浮点数会被截断不能全局这么设。更精细的做法是把接口数据先当字符串拿再单独按字段转数字虽然啰嗦但最安全。5.2 稀疏数组的坑2.1.0 对 table 的 array 部分判定逻辑更加严格默认只有连续且从 1 开始的数字键数组才会被 encode 成 JSON 数组。如果你有一个{[1]a, [3]c}这种稀疏数组默认会被 encode 成{1:a,3:c}这在某些对接方那里会直接类型不匹配。处理方法是注册 sparse 转换函数或者干脆在进 cjson 之前先把稀疏数组补成普通数组。后者更直观序列化结果也更符合大多数后端的预期。-- 把一个稀疏数组压紧 local function tighten(t) local res {} for _, v in ipairs(t) do res[#res1] v end return res end local sparse_tbl {[1]a, [3]c} local json cjson.encode(tighten(sparse_tbl)) -- 结果是 [a,c]5.3 cjson.safe 在业务代码里的姿势在业务逻辑里写cjson.decode(str)如果字符串是坏的会直接 throw error弹出去就得用 pcall 包代码一层套一层非常丑。cjson.safe 返回的格式是nil, err_table我个人的使用习惯是统一封装一个 helperlocal cjson_safe require(cjson.safe) local function parse_json(str) local ok, res pcall(cjson_safe.decode, str) if not ok or type(res) ~ table then return nil end return res end有的朋友直接裸用 cjson.safe但忽略了一个细节cjson.safe 内部已经用 pcall 包了一层返回值可能是nil, expected object or array这种字符串错误也可能是 table。你可以直接判断返回值的类型而不是 ok 值这是我踩过才发现的。6. 常见问题与排障速查表这一节我按踩坑频率排序整理成速查表先给结论再补思路现象直接原因解决办法module cjson not foundcjson.so 不在 package.cpath 搜索范围内手动追加 package.cpath 路径attempt to index a nil value (global cjson)require 失败但代码未中断错误在 require 后加 assert 并打印具体报错bad argument #1 to decode (string expected, got nil)传入 nil 或空字符串decode 前先判空大整数精度丢失cjson 默认按 double 解析用 set_number_type 或按字符串处理Lua 5.3 环境偶发崩溃编译时 LUA_VERSION_NUM 不对用本机版本重编Encode 结果数组/对象和预期不符table 键不连续导致被判定成 object先压紧数组或配置 sparse 转换UTF-8 中文乱码/转义异常源代码文件编码格式问题确保 .lua 文件是 UTF-8 无 BOMencode 默认会输出 UTF-8 原文7. 动手验证性能编解码基准数据接入一个库光能跑还不够性能得心里有数。我拿 luajit 2.1.0-beta3 配合 lua-cjson-2.1.0 做了个小测试数据是一段大约 2KB 的嵌套 JSON循环 10 万次统计总耗时。配置Intel Xeon 2.4GHz 单核、内存 512MB 容器local cjson require(cjson) local payload [[ {name:gateway,version:2.1.0,status:200,items: [1,2,3,4,5,6,7,8,9,10], nested:{enabled:true,ratio:0.25,tags:[a,b,c]}} ]] local start os.clock() for i1, 100000 do local obj cjson.decode(payload) obj.version cjson.encode(obj) end local elapsed os.clock() - start print(string.format(elapsed: %.3fs, elapsed))实测 10 万次 decode encode 大约耗时 2.8 秒也就是每秒能处理三万五到四万次级别。如果换标准 Lua 5.1 性能会下降一些但也在可用范围。如果你做的是 OpenResty 网关这个性能几乎不会成为瓶颈瓶颈永远在业务处理和网络 IO 上。注意不要在循环里反复 require(cjson)Lua 的 package.loaded 会缓存但每次 require 本身也有查表开销应在文件顶部一次性加载。8. 个人体验与后续扩展建议这套 lua-cjson-2.1.0 我前前后后用了大半年从最初直接拿别人编好的 .so 到后来又自己重新编译了两个版本最大的体感是这库虽然小但涉及 ABI 兼容和数据语义的地方非常敏感一定要亲手验证一遍再交付不然出问题定位成本极高。我后来的标准流程很固定先确认 Lua 运行时类型和版本再决定用已编译产物还是自己重编装好之后第一个动作就是跑冒烟测试和压测进业务代码后把所有 decode/encode 包一层统一入口后续好加监控和日志。这样一套下来cjson 这个环节基本不会成为线上故障源。如果后续要在 LuaJIT 下追求更高性能可以关注一下 Rust 写的 dlopen 方案或者自维护的 JSON 解析器不过在 95% 的场景下lua-cjson 2.1.0 合理的隔离部署已经完全够用了。本文还有配套的精品资源点击获取 
长河君 · 2026/9/2 2:22:02 · 阅读 1.2k lua-cjson 2.1.0 接入实战：编译、装载与排坑指南
简介面向Lua开发者的JSON处理库lua-cjson-2.1.0已编译版本可直接在支持平台上加载使用省去源码编译环节。该库采用C实现解析与生成JSON字符串速度快适合游戏开发、Web接口联调、配置文件读写等需要高频处理数据的场景。压缩包共50个文件包含cjson.dll/so动态链接库、头文件、Lua示例脚本、C源码、CMakeLists与编译脚本以及README、LICENSE等文档整体仅239KB轻量易集成。其中json和lua文件可用于测试与演示h/c文件便于二次开发时查看实现细节dll文件则支持require(cjson)直接调用。已有987人学习下载对希望快速接入JSON能力的Lua开发者而言这份预编译包提供了即取即用的完整组件同时保留源码与构建配置方便在不同环境下自行调整。 做后端开发这几年只要项目里碰过 Lua十有八九都绕不开 lua-cjson 这个库。它不是什么花哨的框架就是 Lua 世界里最常用的 JSON 编解码 C 扩展OpenResty 内部集成过很多网关、WAF、游戏服务器的战斗逻辑也都在用。最近我要在纯 LuaJIT 环境里处理一批第三方接口的 JSON 数据又不想改系统全局的 Lua 环境翻出来这份 lua-cjson-2.1.0-已编译的产物干脆把整个接入和排坑过程整理出来。这篇东西不是文档复读是我自己动手编译、装载、压测之后的一些实操经验适合正在折腾 lua-cjson 2.1.0、或者拿到别人编译好的 cjson.so 不知道怎么用的人参考。1. 为什么偏偏是 lua-cjson核心价值与适用场景1.1 JSON 在 Lua 生态里的地位Lua 语言本身非常克制标准库里没有 JSON 编解码能力这和 Python 那种自带 json 模块的设计思路完全不同。但现实项目里无论是和 HTTP API 交互、读写配置文件还是做 Redis 消息序列化JSON 几乎是无处不在的基础格式。这时候就需要一个高性能、稳定、和 Lua 配合紧密的 C 扩展来补上这个缺口。lua-cjson 就是这个生态位上的头号选手。它是 Mark Pulford 写的纯 C 实现底层不依赖任何第三方 JSON 库解析和序列化一条龙。2.1.0 版本在安全性和 UTF-8 处理上做了不少加强专门处理了解析超大数字、空数组、嵌套深结构这些历史遗留问题整体行为比老版本更可控。1.2 为什么强调“已编译”这个状态很多人初学 Lua 扩展时第一个拦路虎不是写代码而是编译。lua-cjson 编译本身不复杂一个 Makefile 就搞定但前提是你的机器上得有匹配的 Lua 头文件、编译器环境、sysroot 都得对得上。更重要的是Lua 版本不同lua_State 结构体内部布局和 API 宏定义都有差异你用 Lua 5.1 的头编译出来的 .so放到 LuaJIT 的环境里可能能跑但放到 Lua 5.4 的环境里就可能直接段错误。“已编译”三个字在这种语境下意味着源码包已经从 GitHub 拉下来、Makefile 执行完毕、cjson.so 文件已经躺在了目录里。你省掉了拉取源码、处理 include 路径、解决链接错误这些步骤直接进入“部署验证”阶段。但这里我要泼一盆冷水拿到已编译产物不代表万事大吉你把 .so 丢进系统后必须要先验证 Lua 的 ABI 兼容性否则运行期崩溃会让你排查到怀疑人生这一点后面我会详细说。2. 接入前的环境核对与装载方案2.1 先确认自己的 Lua 运行时很多人拿到 cjson.so 就直接 require(cjson)然后报错就慌。实际上你应该先花三十秒确认当前 Lua 运行时是什么是标准 Lua 5.1/5.2/5.4还是 LuaJIT可以用lua -v或luajit -v查看。这决定了 cjson 能否直接加载成功因为 lua-cjson 在编译期会通过LUA_VERSION_NUM宏来适配 API不同大版本之间编译出来的二进制不通用。# 检查系统 Lua 版本 lua -v Lua 5.1.5 Copyright (C) 1994-2012 Lua.org, PUC-Rio # 或者如果是 LuaJIT luajit -v LuaJIT 2.1.0-beta3 -- Copyright (C) 2005-2017 Mike Pall如果你发现手头这份已编译的 cjson.so 和系统 Lua 版本不匹配不要灰心往下看第 4 节我会教你从源码重新编译一套属于自己的 cjson.so这个过程完全可控。2.2 动态库装载路径与 package.cpathLua 加载 C 扩展的机制很有意思它不走package.path而是走package.cpath这个变量决定了 .so 文件要去哪里找。默认情况下很多发行版只配置了系统目录比如/usr/local/lib/lua/5.1/?.so如果你的 cjson.so 放在/opt/mylua/lib/直接 require 肯定找不到。实测下来最稳妥的做法是在启动脚本里显式把目录加进去不要污染系统级配置尤其是多项目共存的服务器上。-- 在 main.lua 开头设置 package.cpath package.cpath .. ;/opt/mylua/lib/?.so;/opt/mylua/lib/lua/5.1/?.so local cjson require(cjson) assert(cjson, cjson 加载失败)这里有个细节?.so中问号会被 Lua 替换成 require 的名字。比如你require(cjson.safe)它就会去找cjson/safe.so。lua-cjson 2.1.0 其实带了两个核心模块一个是普通版本cjson一个是安全版本cjson.safe。普通版本在解析非法 JSON 时会直接抛出错误而 safe 版本会把错误包装成一个 table 返回这样可以避免 pcall 的层层包裹。2.3 加载测试与 ABI 冒烟验证拿到 .so 文件先别急着写业务逻辑先跑一个冒烟测试确认二进制和运行时兼容性。我见过有人把 Lua 5.3 编出来的 cjson.so 放到 LuaJIT 下强行使用结果解析正常编码也正常但偶发崩溃这种问题最阴间。-- smoke.lua package.cpath package.cpath .. ;/opt/mylua/lib/?.so local cjson require(cjson) local ok, obj pcall(cjson.decode, {name:test,items:[1,2,3],ok:true}) if not ok then error(cjson decode failed: .. tostring(obj)) end assert(obj.name test, field name mismatch) assert(#obj.items 3, array length mismatch) assert(obj.ok true, boolean mismatch) local encoded cjson.encode({a 1, b {c x}}) assert(encoded {a:1,b:{c:x}}, encode mismatch) print(smoke test passed)如果这步通过了说明 .so 和运行时基本吻合。如果 pass 不了别硬调直接看第 4 节重新编译一份最省事。3. 已编译产物在项目中的落地实践3.1 按项目隔离依赖目录既然都已经拿到已编译的 cjson.so说明你不想在中间环节再折腾。我的建议是目录要隔离别直接扔进/usr/lib64/lua/。把 cjson.so 放到项目自身的lib/目录下和纯 Lua 代码放在一起这样部署时整个目录拷走目标机器上什么都不用装。比如我的一个网关项目结构就是这样的/opt/gateway/ ├── lib/ │ ├── cjson.so # lua-cjson 2.1.0 已编译产物 │ └── resty/ ├── lua/ │ ├── main.lua │ └── handler.lua └── bin/ └── start.sh这样最大的好处是版本可控。系统里某个项目要升 cjson 2.1.1我这边 2.1.0 完全不受影响。做线上服务的人都有体会依赖隔离是保平安的底线。3.2 与 OpenResty / LuaJIT 环境配合的注意点如果你的运行环境是 OpenResty那要特别小心。OpenResty 自带了一份 lua-cjson而且版本可能和你这份 2.1.0 不一样。默认情况下require(cjson)会加载 OpenResty 内置的那个你手动指定 package.cpath 覆盖也行但我不建议在 OpenResty 环境里强行替换系统内置的 cjson。为什么因为 OpenResty 对 cjson 打了自己的补丁比如增加了一些内部缓存优化你要是强行覆盖可能出现 API 行为不一致尤其是cjson.encode对空 table 编码成[]还是{}的处理规则不同版本之间有微妙差异这类问题排查起来非常痛苦。如果是纯 LuaJIT 环境问题不大直接把 cjson.so 放进目录即可。但在用之前最好确认 LuaJIT 是用-DLUAJIT_ENABLE_LUA52COMPAT编译的因为这种编译选项会影响部分 API 语义cjson 通过常规 Lua C API 也能跑但部分字符串处理路径在不同兼容级别下的表现不完全一致实测下来最好全链路做一遍烟雾测试。3.3 环境变量 vs 代码内配置我见过不少项目习惯用LUA_CPATH环境变量来做动态库路径。这招在本地开发时很快但上了容器或者 systemd 服务之后环境变量经常会被改写或遗漏导致启动时报module cjson not found。所以我的建议是在入口代码里显式写 package.cpath不要依赖环境变量。或者两者都配代码里作为兜底。这看起来有点土但确实最不容易出问题运维投拆少一半。4. 从头编译一份自己的 lua-cjson 2.1.04.1 编译准备与参数说明如果你不想继续用别人的已编译产物或者拿到的那份和本机环境不兼容我们从头编一遍。整个过程也就几十秒核心是搞懂 Makefile 里的几个参数。先从 GitHub 拉源码注意 2.1.0 的 release 分支。git clone https://github.com/mpx/lua-cjson.git cd lua-cjson git checkout 2.1.0lua-cjson 的 Makefile 支持几个关键变量LUA_INCLUDE_DIR、LUA_LIBDIR、LUA_VERSION_NUM。这三个直接影响编译产物是否能匹配目标运行时。# 对标准 Lua 5.1 的典型编译 make LUA_INCLUDE_DIR/usr/include/lua5.1 \ LUA_LIBDIR/usr/lib/x86_64-linux-gnu/lua/5.1 \ LUA_VERSION_NUM501 # 对 LuaJIT 2.1 的典型编译 make LUA_INCLUDE_DIR/usr/include/luajit-2.1 \ LUA_LIBDIR/usr/lib/x86_64-linux-gnu/lua/5.1 \ LUA_VERSION_NUM501这里要解释一个很多人困惑的点LuaJIT 的 ABI 兼容的是 Lua 5.1所以 LUA_VERSION_NUM 还是填 501不要填 502 或 504。cjson 源码里用LUA_VERSION_NUM来判断怎么调用 API比如在 Lua 5.2 以后lua_objlen改名成lua_rawlen如果这个宏定义错了编译出来轻则警告重则直接加载失败甚至运行期内存错乱。4.2 编译过程与 CFLAGS 调优lua-cjson 在 2.1.0 相对老版本增加了对 UTF-8 的默认处理默认情况不校验如果你想要更严格的 UTF-8 检查可以打开编码检查宏。我一般不会开因为绝大多数内部 JSON 数据不需要那么严格开了反而降低吞吐。直接编译make LUA_INCLUDE_DIR/usr/include/luajit-2.1 \ LUA_LIBDIR/usr/lib/x86_64-linux-gnu/lua/5.1 \ LUA_VERSION_NUM501编译完成后目录下会生成 cjson.so。你可以用strip把符号表去掉体积缩小大约三分之一加载速度也能快一点。不过带符号版本对线上问题排查更有价值进退取舍看项目。# 可选缩小文件体积 strip cjson.so如果你编译时报找不到lua.h说明 LUA_INCLUDE_DIR 路径不对。先确认头文件位置find /usr -name lua.h 2/dev/null4.3 安装到了系统要不要更新缓存lua-cjson 是纯 C 动态库没有 LuaRocks 那种 module cache 机制只要 .so 文件在磁盘上放对位置即可。放到系统目录如/usr/lib/x86_64-linux-gnu/lua/5.1/时不需要执行ldconfig因为 Lua 不通过 ld.so 缓存查找普通模块它是直接用 dlopen 按文件名拼路径加载的。真正容易出问题的反而是“目录放对了但权限不够”。如果你用非 root 账号跑 Lua而 .so 权限是 700 且 owner 是 root那也会导致加载失败注意一定要给到 755 或 644。5. 从 JSON 精度到稀疏数组的实战配置5.1 数字精度处理lua-cjson 2.1.0 有一个从引入开始就被反复讨论的特性默认情况下cjson.decode会把大整数转成 double导致精度丢失。如果你的接口返回身份证号、雪花ID超过 2^53直接 decode 出来数字会变样。实测这个场景下推荐用cjson.decode_array_with_array_mt或者配合cjson.set_number_type来规避。lua-cjson 2.1.0 允许你把整数保留成 64 位整数类型local cjson require(cjson) cjson.encode_number_precision(14) -- 默认精度其实是14可根据需要调 -- 如果你明确知道有大整数建议把数字格式设为 int cjson.set_number_type(cjson.INT)但要注意把数字类型全改成 INT 后浮点数会被截断不能全局这么设。更精细的做法是把接口数据先当字符串拿再单独按字段转数字虽然啰嗦但最安全。5.2 稀疏数组的坑2.1.0 对 table 的 array 部分判定逻辑更加严格默认只有连续且从 1 开始的数字键数组才会被 encode 成 JSON 数组。如果你有一个{[1]a, [3]c}这种稀疏数组默认会被 encode 成{1:a,3:c}这在某些对接方那里会直接类型不匹配。处理方法是注册 sparse 转换函数或者干脆在进 cjson 之前先把稀疏数组补成普通数组。后者更直观序列化结果也更符合大多数后端的预期。-- 把一个稀疏数组压紧 local function tighten(t) local res {} for _, v in ipairs(t) do res[#res1] v end return res end local sparse_tbl {[1]a, [3]c} local json cjson.encode(tighten(sparse_tbl)) -- 结果是 [a,c]5.3 cjson.safe 在业务代码里的姿势在业务逻辑里写cjson.decode(str)如果字符串是坏的会直接 throw error弹出去就得用 pcall 包代码一层套一层非常丑。cjson.safe 返回的格式是nil, err_table我个人的使用习惯是统一封装一个 helperlocal cjson_safe require(cjson.safe) local function parse_json(str) local ok, res pcall(cjson_safe.decode, str) if not ok or type(res) ~ table then return nil end return res end有的朋友直接裸用 cjson.safe但忽略了一个细节cjson.safe 内部已经用 pcall 包了一层返回值可能是nil, expected object or array这种字符串错误也可能是 table。你可以直接判断返回值的类型而不是 ok 值这是我踩过才发现的。6. 常见问题与排障速查表这一节我按踩坑频率排序整理成速查表先给结论再补思路现象直接原因解决办法module cjson not foundcjson.so 不在 package.cpath 搜索范围内手动追加 package.cpath 路径attempt to index a nil value (global cjson)require 失败但代码未中断错误在 require 后加 assert 并打印具体报错bad argument #1 to decode (string expected, got nil)传入 nil 或空字符串decode 前先判空大整数精度丢失cjson 默认按 double 解析用 set_number_type 或按字符串处理Lua 5.3 环境偶发崩溃编译时 LUA_VERSION_NUM 不对用本机版本重编Encode 结果数组/对象和预期不符table 键不连续导致被判定成 object先压紧数组或配置 sparse 转换UTF-8 中文乱码/转义异常源代码文件编码格式问题确保 .lua 文件是 UTF-8 无 BOMencode 默认会输出 UTF-8 原文7. 动手验证性能编解码基准数据接入一个库光能跑还不够性能得心里有数。我拿 luajit 2.1.0-beta3 配合 lua-cjson-2.1.0 做了个小测试数据是一段大约 2KB 的嵌套 JSON循环 10 万次统计总耗时。配置Intel Xeon 2.4GHz 单核、内存 512MB 容器local cjson require(cjson) local payload [[ {name:gateway,version:2.1.0,status:200,items: [1,2,3,4,5,6,7,8,9,10], nested:{enabled:true,ratio:0.25,tags:[a,b,c]}} ]] local start os.clock() for i1, 100000 do local obj cjson.decode(payload) obj.version cjson.encode(obj) end local elapsed os.clock() - start print(string.format(elapsed: %.3fs, elapsed))实测 10 万次 decode encode 大约耗时 2.8 秒也就是每秒能处理三万五到四万次级别。如果换标准 Lua 5.1 性能会下降一些但也在可用范围。如果你做的是 OpenResty 网关这个性能几乎不会成为瓶颈瓶颈永远在业务处理和网络 IO 上。注意不要在循环里反复 require(cjson)Lua 的 package.loaded 会缓存但每次 require 本身也有查表开销应在文件顶部一次性加载。8. 个人体验与后续扩展建议这套 lua-cjson-2.1.0 我前前后后用了大半年从最初直接拿别人编好的 .so 到后来又自己重新编译了两个版本最大的体感是这库虽然小但涉及 ABI 兼容和数据语义的地方非常敏感一定要亲手验证一遍再交付不然出问题定位成本极高。我后来的标准流程很固定先确认 Lua 运行时类型和版本再决定用已编译产物还是自己重编装好之后第一个动作就是跑冒烟测试和压测进业务代码后把所有 decode/encode 包一层统一入口后续好加监控和日志。这样一套下来cjson 这个环节基本不会成为线上故障源。如果后续要在 LuaJIT 下追求更高性能可以关注一下 Rust 写的 dlopen 方案或者自维护的 JSON 解析器不过在 95% 的场景下lua-cjson 2.1.0 合理的隔离部署已经完全够用了。本文还有配套的精品资源点击获取