Redis的列表（List）是一种双向链表结构，支持从头部和尾部高效地插入、删除元素，常被用来做消息队列、最新动态列表等。但链表式的操作有时不够灵活，比如我们已经往列表里塞了一批任务，中途发现某个位置的数据写错了，又不想把整个列表删掉重来。这种情况下，按索引直接改值显然是最省事的做法，而这正是LSET命令存在的意义。
LSET的基本语法与索引规则
LSET的语法非常简单，接受三个参数：key、index和value。它的作用是把指定key的列表中，位于index位置上的元素替换为新的value。执行成功后返回OK。先用redis-cli感受一下它的行为：
127.0.0.1:6379> RPUSH task:list "任务A" "任务B" "任务C" (integer) 3 127.0.0.1:6379> LSET task:list 1 "任务B-已修正" OK 127.0.0.1:6379> LRANGE task:list 0 -1 1) "任务A" 2) "任务B-已修正" 3) "任务C"
索引的规则和LRANGE、LINDEX一致：正向索引从0开始，0表示头部的第一个元素；负数索引则从尾部倒数，-1表示最后一个元素，-2表示倒数第二个，以此类推。所以LSET mylist -1 "new"就是替换列表尾部的元素。
有一个非常关键的细节需要注意：如果给定的key不存在，Redis会报错(error) ERR no such key；如果索引超出列表的实际范围，则会报错(error) ERR index out of range。也就是说，LSET永远不会自动创建key，也不会静默忽略非法索引，这是一种fail-fast的设计。与之对比，很多编程语言中对越界索引的数组赋值可能直接抛异常导致程序中断，而Redis把错误以返回值的形式交给客户端处理，因此在代码中务必捕获并判断这类错误，避免把正常流程打断。
LSET的时间复杂度与适用场景分析
Redis列表的底层实现是quicklist（由ziplist或listpack组成的双向链表），按索引访问某个元素需要从头或尾遍历到目标位置，所以LSET的时间复杂度是O(N)，N表示需要跳过的元素个数。Redis在实现上会做一个优化：如果索引是负数或者更靠近尾部，就从尾部开始遍历，否则从头部开始。因此访问头尾附近的元素非常快，访问列表中部的元素则相对较慢。
这意味着LSET适合以下两类场景：第一类是列表长度较短的操作，比如几十上百个元素的商品标签、配置项列表，随便改哪个位置都没压力；第二类是只操作头尾附近的元素，比如一个待处理的消息队列，只需要修正队列头部的下一条任务。如果你的列表存了十万条数据，还要频繁按随机索引修改中间的元素，那LSET就不是好选择了，更合理的做法是使用Hash结构，把索引或业务ID作为field，用HSET做到O(1)级别的更新。
另外要提醒一点，LSET是对已有元素的覆盖式修改，如果业务上需要的是插入新元素，应该用LSET的兄弟命令LINSERT，它可以在指定元素的前面或后面插入新值。两者不要混用，否则很容易出现数据错位的诡异问题。
代码实战：在应用中安全地使用LSET
下面以Python的redis-py客户端为例，演示一个常见的业务场景：待办事项列表中某一项的内容发生了变更，需要原地更新。注意要处理好key不存在和索引越界两种异常情况。
import redis
r = redis.Redis(host='127.0.0.1', port=6379, decode_responses=True)
def update_todo(user_id, index, new_content):
key = f"todo:{user_id}"
try:
# 先确认索引合法，再执行修改
length = r.llen(key)
if length == 0:
print("列表不存在或为空，跳过更新")
return False
# 将负索引转换为正向索引做统一校验
if index < 0:
index += length
if index < 0 or index >= length:
print(f"索引越界：合法范围是 0 到 {length - 1}")
return False
r.lset(key, index, new_content)
return True
except redis.ResponseError as e:
print(f"Redis返回错误: {e}")
return False
r.rpush("todo:1001", "写周报", "回复邮件", "准备评审材料")
update_todo("1001", 1, "回复邮件-已完成")
print(r.lrange("todo:1001", 0, -1))
# 输出: ['写周报', '回复邮件-已完成', '准备评审材料']
如果需要在一次网络往返中完成先查后改的操作，避免并发窗口带来的问题，可以使用WATCH做乐观锁，或者干脆用Lua脚本把逻辑封装成原子操作。比如下面这个脚本实现了仅当目标位置元素等于旧值时才替换，相当于列表版的CAS：
-- KEYS[1]为列表key，ARGV[1]为索引，ARGV[2]为期望的旧值，ARGV[3]为新值
local old = redis.call('LINDEX', KEYS[1], ARGV[1])
if old == ARGV[2] then
redis.call('LSET', KEYS[1], ARGV[1], ARGV[3])
return 1
end
return 0
这种写法在多客户端并发修改同一位置的元素时特别有用，能防止后写入的数据把先写入的更新悄悄覆盖掉。总的来说，LSET是一个小而美的命令，语法简单，但要真正用好它，关键是理解索引规则、越界报错机制和O(N)的复杂度特性，再根据列表规模和访问模式判断它是否是当前场景下的最优解。
Redis LSETRedis列表Redis命令修改时间：2026-09-14 06:52:31