Lua 入门：写给 Redis 脚本使用者的极简教程

Redis 从 2.6 开始支持 Lua 脚本，核心目的是把多个命令打包成原子操作。本文面向已经会用 Redis、但还没写过 Lua 脚本的同学，只讲最常用、最实用的部分，学完就能写出常见的限流、加锁、库存扣减脚本。

一、为什么 Redis 需要 Lua

Redis 单条命令是原子的，但多条命令组合起来就不是了。比如经典的「查库存 → 判断 → 扣减」：

GET stock:1001      # 返回 10
# 业务代码判断 10 > 0
DECR stock:1001     # 返回 9

并发时两个客户端可能都读到 10，然后都执行 DECR，导致超卖。

Lua 脚本在 Redis 里作为一个整体执行，中间不会被其他命令打断，天然解决了这类问题。而且脚本在 Redis 服务端执行，还能减少网络往返。

二、本地 Lua 环境准备

2.1 安装 Lua

macOS：

brew install lua
lua -v

Ubuntu / Debian：

sudo apt update
sudo apt install lua5.1
lua5.1 -v

Windows：

从 Lua 官方 下载源码或预编译二进制，也可以直接用 Lua for Windows。

Docker（最省事）：

docker run --rm -it nickblah/lua:5.1 lua -v

2.2 第一个本地 Lua 程序

创建 hello.lua：

print("hello, lua")

运行：

lua hello.lua

2.3 用 Redis 验证脚本

如果你本地有 Redis，可以直接用 redis-cli 跑脚本文件：

redis-cli --eval myscript.lua key1 key2 , arg1 arg2

注意 , 前后都有空格：, 左边是 KEYS，右边是 ARGV。

2.4 编辑器推荐

• VS Code：插件 Lua（sumneko）或 Lua Language Server。
• IDEA / WebStorm：安装 EmmyLua 插件。
• Neovim：lua_ls + lspconfig。

三、Hello World：第一个 Redis Lua 脚本

EVAL "return 'hello, redis lua'" 0

• EVAL 是执行 Lua 脚本的命令。
• 后面的 0 表示脚本用到的 key 数量是 0。
• return 把结果返回给客户端。

带 key 和参数的版本：

EVAL "return redis.call('GET', KEYS[1])" 1 user:1
# 等同于 GET user:1

EVAL "return redis.call('SET', KEYS[1], ARGV[1])" 1 user:1 alice
# 等同于 SET user:1 alice

• KEYS[1] 对应第 1 个 key，KEYS[2] 对应第 2 个，以此类推。
• ARGV[1] 对应第 1 个额外参数。
• 所有 ARGV 都是字符串，如果需要数字，要在 Lua 里做类型转换。

四、Lua 基础：Redis 场景够用的子集

4.1 变量与类型

Lua 是动态类型语言，常用类型有：nil、boolean、number、string、table。

local name = "alice"      -- 字符串
local age = 30            -- 数字，不区分 int / float
local ok = true           -- 布尔
local empty = nil         -- 空

注意：

• 局部变量用 local，否则会成为全局变量。Redis 脚本里建议一律用 local。
• 条件判断时，0 和空字符串 '' 都是 true，只有 nil 和 false 是 false。

local a = 0
if a then
    return "yes"    -- 会执行这里
end

4.2 字符串与数字转换

local s = "42"
local n = tonumber(s)      -- 转成数字 42
local s2 = tostring(n)     -- 转成字符串 "42"

local a = "10"
local b = "3"
local c = a + b            -- 13，自动把字符串当数字

在 Redis 脚本里，更推荐显式转换，避免意外：

local count = tonumber(redis.call('GET', KEYS[1])) or 0

4.3 表（table）：数组 + 字典

表是 Lua 唯一的数据结构，既能当数组用，也能当字典用。

-- 数组（下标从 1 开始）
local arr = {"a", "b", "c"}
return arr[1]    -- "a"

-- 字典
local dict = {name = "alice", age = 30}
return dict.name -- "alice"

遍历数组：

local arr = {"a", "b", "c"}
for i, v in ipairs(arr) do
    print(i, v)
end
-- 输出：
-- 1 a
-- 2 b
-- 3 c

遍历字典：

local dict = {name = "alice", age = 30}
for k, v in pairs(dict) do
    print(k, v)
end

4.4 条件判断

local n = 10
if n > 20 then
    return "big"
elseif n > 5 then
    return "medium"   -- 会返回这个
else
    return "small"
end

4.5 循环

-- for 循环
for i = 1, 5 do
    print(i)
end

-- while 循环
local i = 1
while i <= 5 do
    print(i)
    i = i + 1
end

Redis 脚本里循环要慎用，避免执行时间过长阻塞主线程。

4.6 函数

local function add(a, b)
    return a + b
end

return add(1, 2)  -- 3

五、Lua 原理浅析

理解 Lua 的运行机制，能帮你写出更稳的 Redis 脚本。

5.1 解释器与字节码

Lua 不是纯解释执行。它会把源码编译成字节码（bytecode），然后在 Lua 虚拟机（VM）上运行。

luac -o hello.luac hello.lua    -- 编译成字节码
lua hello.luac                   -- 运行字节码

Redis 内部集成的也是 Lua VM，脚本第一次执行时会先编译成字节码，之后再执行就复用这个结果。所以长脚本第一次跑会慢一点，后续重复执行会快一些。

5.2 内存回收机制

Lua 使用自动垃圾回收（Garbage Collection, GC），主要策略是增量式标记-清除（incremental mark-and-sweep）。Lua 5.4 还引入了分代 GC 模式。

对 Redis 脚本来说，关键点是：

• 脚本运行期间创建的 table、string 等临时对象，由 Lua GC 自动回收。
• Redis 脚本通常很短，GC 压力不大。
• 不要在脚本里构造超大 table 或缓存大量中间结果，否则可能触发 GC 暂停，阻塞 Redis。

5.3 Table 是核心

Lua 的 table 本质上是一个哈希表 + 数组的混合结构：

• 用连续整数索引时，底层按数组优化，访问快。
• 用字符串或其他类型当 key 时，底层是哈希表。

这也是 Lua 能用 table 模拟数组、字典、对象、模块的原因。

5.4 Redis 中的 Lua 沙箱

Redis 对 Lua 做了严格限制：

• 不能加载外部库（如 io、os 大部分功能被禁用）。
• 不能发起网络请求。
• 不能访问文件系统。
• 只能调用 Redis 提供的 API（如 redis.call、redis.log）。

这个沙箱保证了脚本安全，但也意味着你不能直接在脚本里读系统时间（os.time 被禁用），需要把时间作为 ARGV 传进去。

六、Redis 脚本核心 API

6.1 redis.call 与 redis.pcall

• redis.call(...)：调用 Redis 命令，出错时直接抛出 Lua 错误，脚本会终止。
• redis.pcall(...)：调用 Redis 命令，出错时返回错误对象，脚本继续执行。

-- call 版本：key 不存在会报错
local v = redis.call('GET', 'non_existent_key')

-- pcall 版本：可以捕获错误
local ok, err = pcall(redis.call, 'GET', 'non_existent_key')
if not ok then
    return "error: " .. tostring(err)
end

一般推荐：

• 简单脚本用 redis.call，逻辑更清晰。
• 需要容错时用 redis.pcall 或外层 pcall。

6.2 返回值

Lua 脚本可以返回单个值、数组或表：

-- 返回单个值
return redis.call('GET', KEYS[1])

-- 返回多个值
return {redis.call('GET', KEYS[1]), redis.call('GET', KEYS[2])}

Redis 会把 Lua 的 table 转成数组返回给客户端。

6.3 KEYS 与 ARGV 的规范

Redis Cluster 要求脚本里用到的 key 都必须放在 KEYS 中，这样 Redis 才能判断脚本是否跨 slot。ARGV 里只能放非 key 参数。

EVAL "return redis.call('SET', KEYS[1], ARGV[1])" 1 mykey myvalue

这里 mykey 是 key，myvalue 是 value。

七、实战：常见 Redis Lua 模式

7.1 限流（滑动窗口）

限制某个用户在 60 秒内最多请求 100 次：

local key = KEYS[1]
local window = tonumber(ARGV[1])      -- 窗口大小，毫秒
local limit = tonumber(ARGV[2])       -- 限制次数
local now = tonumber(ARGV[3])         -- 当前时间戳，毫秒

-- 清理窗口外的请求记录
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)

-- 统计当前窗口内的请求数
local count = redis.call('ZCARD', key)

if count < limit then
    redis.call('ZADD', key, now, now .. "_" .. count)
    redis.call('PEXPIRE', key, window)
    return 1   -- 允许通过
else
    return 0   -- 拒绝
end

调用：

EVAL "...脚本..." 1 rate:user:1 60000 100 1690000000000

7.2 分布式锁（可重入简化版）

local key = KEYS[1]
local token = ARGV[1]
local ttl = tonumber(ARGV[2])

local current = redis.call('GET', key)
if current == false or current == token then
    redis.call('SET', key, token, 'PX', ttl)
    return 1
else
    return 0
end

7.3 库存扣减（防超卖）

local key = KEYS[1]
local delta = tonumber(ARGV[1])

local stock = tonumber(redis.call('GET', key)) or 0
if stock < delta then
    return -1    -- 库存不足
end

redis.call('DECRBY', key, delta)
return stock - delta

7.4 批量删除符合某种前缀的 key

注意：生产环境慎用 KEYS 命令，这里仅作语法示例，大数据量请用 SCAN。

local pattern = ARGV[1]
local keys = redis.call('KEYS', pattern)

for i, k in ipairs(keys) do
    redis.call('DEL', k)
end

return #keys

7.5 条件更新（CAS 简化版）

local key = KEYS[1]
local expected = ARGV[1]
local newValue = ARGV[2]

local current = redis.call('GET', key)
if current == expected then
    redis.call('SET', key, newValue)
    return 1
else
    return 0
end

八、调试、常见坑与最佳实践

8.1 调试脚本

1. 先用本地 Redis 跑：redis-cli --eval script.lua key1 key2 , arg1 arg2
   • 注意 , 前后有空格，, 左边是 KEYS，右边是 ARGV。
2. 打印日志：Lua 脚本里不能直接用 print 输出到客户端，但可以用 redis.log(redis.LOG_NOTICE, msg) 写到 Redis 日志。

redis.log(redis.LOG_NOTICE, "current stock: " .. tostring(stock))

3. 本地先用 lua 命令跑语法：不依赖 Redis 也能检查基础语法错误。

8.2 常见踩坑清单

8.3 性能建议

• 脚本尽量短小，只处理一个原子逻辑单元。
• 不要在 Lua 里做复杂计算或大量循环。
• 大 key 操作（如 HGETALL 几十万字段）不要在脚本里做。
• 热 key 尽量缩短 TTL 或做拆分，避免单脚本长时间占用。
• 对执行时间没把握的脚本，先用 redis-cli --latency-history 或 SLOWLOG 观察影响。

九、总结

Redis Lua 脚本不需要你成为 Lua 专家，掌握下面几点就能覆盖 80% 的场景：

1. 本地能跑 Lua，能写 .lua 文件并用 redis-cli --eval 测试。
2. local 变量、number / string / table 三种类型。
3. tonumber() / tostring() 转换，ipairs() / pairs() 遍历，table.concat 拼接。
4. Lua 是编译成字节码在 VM 上运行，GC 自动回收，Redis 里是沙箱环境。
5. redis.call() 调用命令，KEYS[n] 和 ARGV[n] 传参，集群 key 必须放 KEYS。
6. 脚本整体原子执行，适合「读 → 判断 → 写」的复合操作。
7. 注意 ARGV 是字符串、缺失 key 返回 false、避免长脚本阻塞、写命令要确定性。

限流、分布式锁、库存扣减、条件更新这些高频场景，本质上都是同一个模式：先读数据，在脚本里做判断，再决定写什么。把这一点练熟，Redis Lua 就入门了。

如果你在 Redis Lua 脚本里踩过什么坑，欢迎在评论区分享。

• 数据库

• Lua
• Redis
• 脚本
• 缓存
• 原子操作

方糖猫（大可）

18 年后端架构，现在独立做 AI 产品。这里记录 AI 视频、AI Agent 与工程实践。