6.3 标准库巡礼与沙箱边界

6.3 标准库巡礼与沙箱边界

本节摘要：Lua 的标准库共九个家族，全部以命名空间表的形式提供、全部可 require、也全部可被宿主没收。本节先按辖区巡礼（基本库、字符串、表、数学、位运算、IO、OS、调试、包管理），高频函数点名带例，然后进入压轴：沙箱的三层构造——环境白名单、库裁剪、错误隔离——并抄录 Redis 沙箱的真实限制清单。

打开行李箱

与"带电池"的大标准库语言不同，Lua 的家当是一口小行李箱：九个库、每库几十个函数、全部是纯 Lua 友好的命名空间表（第 5 章的轻派风格——库自己就不用面向对象）。这份克制是刻意为之：家当越少，越容易看管——宿主要没收哪件、替换哪件、重实现哪件，都只是操作一张表的事。

安全区巡礼

基本库（_G 上的函数）：语言自身的操作——pairs、ipairs、next、select、tonumber、tostring、type、rawget 一族、load、dofile、error、assert、pcall、setmetatable、getmetatable。全部已在各章出场，其中 load 的环境参数是沙箱第一层的钥匙。

string 库：第 4 章整章的主角（find/match/gmatch/gsub/sub/rep/format/byte/char）。顺带说明一个常见误会：库里没有现成的 split 或 gsplit 函数——文本分割用 4.2 节题五的 gmatch 惯用法（惰性匹配加尾分隔符补位）自己拼，这是社区几十年不变的惯例。

table 库：第 3 章的 insert/remove/concat/sort/move/pack/unpack。

math 库：常客点名——math.floor/ceil 取整、math.abs/max/min、math.sqrt、math.huge 与 math.pi 常量、math.random 随机数（配合 math.randomseed，5.4 自动播种）、math.fmod（取模，符号跟被除数的 C 风格版本——与 % 的差异留意）、math.tointeger、math.type、math.ult（无符号比较）：

> math.randomseed(2026)
> math.random(1, 6), math.random(1, 6), math.random(1, 6)
4	2	6
> math.tointeger(3.0), math.tointeger(3.5)
3	nil
​

utf8 库（5.3 起）：utf8.len 按码点数长度、utf8.codepoint 与 utf8.char 码点转换、utf8.codes 迭代——中文文本统计长度的正确答案：

> #("脚本语言"), utf8.len("脚本语言")
12	4
> for _, cp in utf8.codes("Lua脚本") do io.write(cp, " ") end
76 117 97 25253 26412
​

coroutine 库：下一章主角，沙箱一般保留（纯计算，无越界能力）。

bit32 库（5.2 引入、5.3 起弃用）：位运算的过渡方案，5.3 之后直接用语言级位运算符（1.4 节），跨到 5.1 现场则用 LuaJIT 的 bit 库。维护老代码看到它别慌，认得即可。

看管区巡礼

io 库：文件与标准流。io.open(path, mode) 返回文件句柄（成功）或 nil 加错误串——永远要检查；file:read("l") 读一行、("a") 读全部、("n") 读数字；file:write、file:lines 迭代行、io.write/print 走标准输出。两个寄宿要点：其一，标准输出在宿主里未必是终端（OpenResty 的 worker 里 print 进错误日志），别依赖它做业务日志；其二，io.popen 能起子进程，是沙箱的绝对禁区。

os 库：时间与环境。os.time（秒级时间戳）、os.date（格式化）、os.clock（CPU 秒，测耗时）、os.getenv（读环境变量——配置来源也是泄露渠道）、os.exit（退宿主进程——脚本能杀宿主，沙箱必禁）、os.remove/rename（动文件系统）。

debug 库：6.2 节的定位三件套加上 sethook、getlocal/setlocal、getupvalue/setupvalue——能窥视与篡改一切局部状态。调试利器、沙箱眼中钉。

package 库：require 的家（6.1 节）。package.loadlib 能加载任意动态库——等于给脚本开了执行任意 C 的口子，高权限环境才留。

沙箱三层构造

现在把三层的完整代码拼出来。目标：跑一段不可信脚本，只给它计算能力与三个白名单函数：

local function run_sandboxed(code, budget)
    -- 第一层：白名单环境
    local env = {
        -- 保留的安全家当（整表借出）
        math   = { floor = math.floor, sqrt = math.sqrt, huge = math.huge },
        string = { format = string.format, upper = string.upper },
        table  = { concat = table.concat, insert = table.insert },
        -- 语言层基本件
        pairs = pairs, ipairs = ipairs, type = type, tonumber = tonumber,
        select = select, error = error, assert = assert, setmetatable = setmetatable,
        -- 业务注入的宿主能力
        redis_call = function(cmd, ...) return ("MOCK %s"):format(cmd) end,
    }

    -- 第二层其实已由第一层达成：环境里根本没有 io os debug package
    -- 再加一道：防逃逸 —— 剔除危险元方法的可能路径（按需加严）

    local chunk = assert(load(code, "sandbox", "t", env))
    -- 第三层：错误隔离
    local ok, result = xpcall(chunk, function(err)
        return { err = tostring(err), trace = debug.traceback(nil, 2) }
    end)
    return ok, result
end

local ok, r = run_sandboxed([[
    return ("sum=%d"):format(math.floor(1.2) + #("abc"))
]])
print(ok, r)                    -- true	sum=4

local ok2, r2 = run_sandboxed([[
    local f = io.open("/etc/passwd")
]])
print(ok2, r2.err)              -- false	（attempt to index a nil value ... global 'io'）
​

三层各自的分工：环境白名单决定"看得见什么"（io 根本不在环境里，不是"禁止访问"而是"不存在"）；错误隔离决定"炸不炸宿主"（xpcall 壳）；库裁剪（第二层）是在共享环境（不给独立 _ENV）时的补充手段——从 _G 里把 io、os 置 nil。独立环境法更干净，共享裁剪法更省内存，按场景选。

三道防线之外还有第四道预算防线：脚本写个死循环怎么办？环境白名单挡不住 while true do end。工程答案是指令预算——宿主用调试钩子（debug.sethook 的 count 事件）每 N 条指令检查一次，超限抛错；Redis 的脚本超时机制（busy script 硬超时后允许 SCRIPT KILL）就是这一层的产物。沙箱的完整性必须算上"时间"这一维，否则一个死循环比一次文件访问更能打死宿主。

Redis 的沙箱清单

四大现场里沙箱最成体系的是 Redis。抄录它的真实规则（细节随版本演进，主干稳定）：

• 环境里没有 io、os（时间相关的 os.time 也拿不到，保证脚本可重放）、debug、package/require——脚本自包含；
• 注入 redis 表（call 与 pcall 两个函数）与 KEYS、ARGV 两张参数表——宿主能力全部经此门；
• 非确定性禁令：早期版本禁用 math.random 与带种子的随机（后来改为每脚本自动重播种但仍写进文档告诫），因为主从复制靠重放脚本，非确定输出会劈开主从；
• 不能创建全局变量（写全局直接报错，环境是保护过的）——脚本只能操作局部；
• 必须受控退出：脚本长跑触发 busy script 阈值后，服务端只接受有限的干预命令，最终可被 SCRIPT KILL 或以 SHUTDOWN NOSAVE 收场；
• 错误即停止：脚本内未捕获错误由宿主壳接住，返回错误响应给客户端，服务进程无恙——这正是 6.2 节防护壳的 C 侧实现（lua_pcall）。

这份清单是"寄宿之道"在安全维度的完整注脚：宿主开放的能力=白名单表的内容，其余一切，对脚本而言不存在。

💡 关键直觉：沙箱不是"禁止清单"思维，是"存在清单"思维。与其枚举一万条禁令，不如只给一张白桌——桌上没有的，房客连想都想不到。Lua 的 _ENV 机制让这件事的成本低到三行代码。

文件处理的两个成熟模式

看管区并非禁区，宿主授权的场景下 io 库有它的战场。两个模式值得记住。

整体读入优先。文件不大就一次读完再处理，比逐行读少系统调用、少句柄存活时间：

local function read_config(path)
    local f, open_err = io.open(path, "r")
    if not f then return nil, open_err end
    local content = f:read("a")            -- 全量读入
    f:close()                              -- 尽早关闭
    return content
end
​

行迭代器加 guard。大文件流式处理用 lines 迭代，每步包壳防单行烂数据炸全局：

local function each_line(path, fn)
    local f, err = io.open(path, "r")
    if not f then return nil, err end
    local n = 0
    for line in f:lines() do
        n = n + 1
        local ok, e = pcall(fn, line, n)
        if not ok then f:close(); return nil, ("line %d: %s"):format(n, e) end
    end
    f:close()
    return n
end

local count, err = each_line("access.log", function(line)
    if line:match("^%s*$") then error("blank line", 0) end
end)
​

错误带上行号、句柄保证关闭（更严格的写法用 5.4 的 <close> 属性）——日志清洗、批量导入的骨架就这两段。注意这些代码出现在脚本层的前提是宿主给了 io 权限；在 Redis 与 OpenResty 的沙箱里，同款逻辑要换成宿主提供的专有接口（SCRIPT 载入、共享日志）——模式迁移，权限随宿主。

收编 collectgarbage

基本库里还有个常被忽略的成员：collectgarbage，垃圾回收器的控制面板。常用调用三个：

collectgarbage("count")        -- 当前已用内存，单位 KB（排错第一步：看内存涨不涨）
collectgarbage("collect")      -- 全量回收（测试内存泄漏时做基线）
collectgarbage("step", 200)    -- 增量推进一步（5.4 还有 "incremental" 与 "generational" 模式切换）
​

脚本内存缓慢上涨时，"count" 前后对比是最快的第一诊断；定期 "step" 让宿主把 GC 摊进自己的空闲时间片（游戏每帧步进，避免集中停顿）——回收的节奏也是宿主的调度权之一，这句注脚到第 9 章工程习惯里还会出现。

时间的三张面孔

os 库的时间函数是脚本里最常见的"宿主依赖"，三张面孔分工不同：

> os.time({ year = 2026, month = 8, day = 20, hour = 9 })   -- 表转时间戳
1755648000
> os.time()                                                 -- 当前时间戳（秒）
1755690000（依运行时刻）
> os.date("%Y-%m-%d %H:%M:%S")                              -- 时间戳转文本
2026-08-20 15:40:00（依运行时刻）
> os.date("!%Y-%m-%dT%H:%M:%SZ")                            -- UTC 加 Z 后缀（日志规范）
2026-08-20T07:40:00Z
> os.clock()                                                -- CPU 时间（秒，测耗时用）
0.012
> os.difftime(t2, t1)                                       -- 差值
7200
​

三个坑值得点名。os.time 无参才是"现在"，传表是"指定时刻转戳"——签名重载容易看漏。os.date 默认本地时区，日志要 UTC 就加叹号前缀（!）配 Z 后缀，跨时区排障时这是救命细节。os.clock 测的是 CPU 时间不是墙钟——脚本做纯计算用它测耗时准确；做 IO 等待的耗时测量要用 os.time 差值（或宿主的高精度钟，9.2 节的 now_ns）。Redis 沙箱禁掉整个 os 时间的原因（可重放性）在 8.3 节已经讲过——同一个函数，在哪个家有什么待遇，取决于它碰不碰"不确定性"。

字节序与打包的纯 Lua 实现

设备与协议现场常要拼二进制帧。string.byte 与 char 配合位运算做打包器（5.3 起）：

local function pack_u16(v)
    return string.char(v // 256 % 256, v % 256)         -- 大端两字节
end

local function unpack_u16(s, pos)
    local hi, lo = s:byte(pos, pos + 1)
    return hi * 256 + lo, pos + 2
end

local frame = pack_u16(0x0102) .. pack_u16(4000) .. "ok"
print(#frame)                       --> 6
local code, next_pos = unpack_u16(frame, 1)
local size, after = unpack_u16(frame, next_pos)
print(("%x %d %s"):format(code, size, frame:sub(after)))    -- 102 4000 ok
​

打包用 // 整除拆高低字节、解包用 byte 取值合成——位运算与字节函数的标准配合。长度前缀帧（两字节长度加负载）是协议世界的通用形，十几行就是完整的读写器。要浮点与更复杂的布局时，5.3 的 string.pack 与 string.unpack 内置函数一步到位（格式串与 C 的 printf 风格同宗）——自己写的价值在于过程可控（老版本兼容、特殊字节序），内置的价值在于简洁，按现场版本选。

本节要点回顾

• 九库分两区：安全区（string/table/math/utf8/基本库/coroutine）纯计算，看管区（io/os/debug/package）各有越界能力；
• utf8 库是中文文本的正确量尺（utf8.len 对 "#(" 之谜的答案）；bit32 已弃用认得即可；
• io.open 要检查返回、popen 是绝对禁区；os.exit 能杀宿主进程、os.getenv 是配置来源也是泄露渠道；
• 文件两模式：整体读入优先、行迭代加 guard——模式迁移到沙箱场景时换宿主接口，权限随宿主；
• collectgarbage 是 GC 面板：count 诊断、collect 基线、step 摊停顿——回收节奏也是宿主调度权；
• 沙箱三层：环境白名单（存在清单）、库裁剪（共享环境时）、错误隔离（xpcall 壳），外加第四道指令预算防线（sethook 计数，防死循环）；
• Redis 清单：无 io/os/require、注入 redis 表与 KEYS/ARGV、禁全局写入、非确定性受限、超时可杀、错误不停服——白名单思维的教科书实现。

行李清点完毕。下一章进入协程——脚本"自愿让出执行权"的艺术，也是宿主与脚本共享时间片的正式协议。