在大多数场景下，我们使用Redis的字符串类型时，都是通过SET整体写入一个值，再用GET整体读出。但有些业务场景只希望改动字符串中的一部分内容，比如修改一个固定长度编码中的某几位、更新位图中的某一段标记位。如果每次都用GET取出完整字符串、在应用层改完再SET回去，不仅多了两次网络往返，还可能带来并发覆盖问题。Redis提供的SETRANGE命令可以直接在服务端完成指定位置的覆盖写入，本文将围绕它的语法、行为细节和实战注意事项展开讲解。
SETRANGE的基本语法与执行逻辑
SETRANGE命令的格式为SETRANGE key offset value，作用是把key对应字符串从offset位置开始的部分，替换为参数value的内容。如果value的长度超过了从offset到字符串末尾的剩余空间，字符串会自动被延长以容纳全部内容；如果offset超出了当前字符串的长度，中间空缺的部分会用零字节（\x00）填充，形成所谓的空洞。
来看一个最基础的例子，先设置一个字符串，再从第4个字节开始覆盖：
127.0.0.1:6379> SET greeting "Hello World" OK 127.0.0.1:6379> SETRANGE greeting 6 "Redis" (integer) 11 127.0.0.1:6379> GET greeting "Hello Redis"
从输出可以看到，SETRANGE执行后返回一个整数，这个返回值是覆盖操作完成之后字符串的总长度，而不是被修改的字节数。这一点在实际使用中容易被误解，尤其是当offset超出原字符串长度时，返回值会明显大于value本身的长度，因为空字节填充的部分也被计算在内了。
还需要注意，SETRANGE中的offset是以字节为单位而不是字符数。如果value中包含中文等多字节字符，一个UTF-8汉字通常占3个字节，此时按字符数计算偏移量会导致写入位置错乱，最终得到乱码。处理非ASCII内容时，一定要先在应用层确认字节偏移，或者尽量对二进制安全的数据使用该命令。
key不存在时的行为与内存空洞问题
当目标key不存在时，SETRANGE会先将key初始化为空字符串，再执行覆盖写入。这意味着即使是一个全新的key，也可以直接使用SETRANGE而无需先SET空值，这在某些场景下能减少一次命令交互。
127.0.0.1:6379> EXISTS userinfo (integer) 0 127.0.0.1:6379> SETRANGE userinfo 0 "uid:1001" (integer) 8 127.0.0.1:6379> GET userinfo "uid:1001"
但另一种情况就需要格外警惕了：如果对一个不存在的key使用了很大的offset，Redis会先用零字节填充前面所有的空白区域。例如执行SETRANGE bigkey 1000000 "x"，会直接产生一个约1MB的字符串，其中绝大部分是空字节。官方文档特别提醒，这种操作可能被用来构造巨大的内存空洞，间接造成内存耗尽攻击。因此在开放给外部调用的接口中，一定要对offset参数做严格的范围校验，避免用户传入任意大的偏移量。
从内存角度看，Redis的字符串底层是SDS（简单动态字符串）结构，SETRANGE在写入前会通过sdsgrowzero等函数确保空间充足，需要扩展时会触发内存重新分配。频繁对同一key执行大范围扩展写入，会产生一定的内存分配压力，建议在业务允许的情况下预估好总长度，一次性分配到位。
实战案例：位图统计与固定格式数据的局部更新
SETRANGE最典型的应用之一是用户签到位图。假设用一个字符串记录一年365天的签到情况，每天占一个字节，第几天签到就在对应偏移写入1。初始时可以把整个字符串初始化为全零，之后每天只需一条命令即可更新：
import redis
r = redis.Redis(host='127.0.0.1', port=6379)
KEY = 'user:1001:sign:2024'
TOTAL_DAYS = 366
# 初始化全零字符串，避免SETRANGE产生隐式分配
if not r.exists(KEY):
r.setrange(KEY, TOTAL_DAYS - 1, b'\x00')
# 第128天签到，在该偏移位置写入1
day = 128
r.setrange(KEY, day - 1, b'\x01')
# 读取第200天的状态
status = r.getrange(KEY, 199, 199)
print('第200天签到状态:', status)上面的代码同时用到了SETRANGE和它的姐妹命令GETRANGE，两者一个负责区间写入、一个负责区间读取，配合起来可以高效处理定长记录。这里预先初始化全零字符串的目的，是让后续每天的写入都发生在已有空间内，避免每次都触发SDS扩容，同时统计总长度也更加稳定。
另一个常见场景是固定格式的编码数据，比如一个16字节的记录中，前4字节是状态码、中间8字节是时间戳、后4字节是校验值。状态变化时只需覆盖前4字节，而不必读取和回写整个记录：
import struct
KEY = 'record:device:5001'
# 写入完整记录：状态1 + 时间戳 + 校验和
full = struct.pack('>IQI', 1, 1718000000, 3721)
r.set(KEY, full)
# 仅更新状态码为3，偏移0写入，不影响其余12字节
r.setrange(KEY, 0, struct.pack('>I', 3))
data = r.get(KEY)
status, ts, check = struct.unpack('>IQI', data)
print('状态:', status, '时间戳:', ts, '校验:', check)这种做法的好处是原子性的：单条Redis命令本身就是原子的，局部覆盖不会出现应用层读改写过程中被其他客户端并发覆盖的竞态问题。相比先GET再SET的两步操作，也不需要引入事务或Lua脚本来保证一致性。
SETRANGE与相关命令的对比及使用建议
Redis中涉及字符串修改的命令主要有SET、APPEND和SETRANGE三者，它们的定位各不相同，可以通过下表直观对比：
| 命令 | 作用位置 | 是否延长字符串 | 典型场景 |
|---|---|---|---|
| SET | 整体替换 | 由新值长度决定 | 全量写入 |
| APPEND | 末尾追加 | 总是延长 | 日志拼接、计数缓冲 |
| SETRANGE | 指定偏移覆盖 | 按需延长并填零 | 位图、定长记录局部更新 |
在使用建议方面，有几点值得强调。第一，offset务必做上界校验，防止意外的内存空洞；第二，处理多字节文本时先确认字节偏移，必要时改用应用层拼装后整体SET；第三，如果一次业务操作需要覆盖多个不连续的区间，可以将多条SETRANGE放进MULTI事务或Pipeline中批量执行，减少网络往返；第四，注意GETRANGE的区间参数是闭区间且支持负数索引，与SETRANGE的单一起点偏移在语义上并不对称，混用时容易踩坑。
总结来说，SETRANGE是一个偏底层但非常实用的字符串修改命令，它把“定位到指定位置再写入”的工作下沉到了Redis服务端，既省去了应用层的读改写流程，又天然保证了单命令的原子性。只要理解了字节偏移、零填充和返回值这三个关键细节，并在接口层守住offset的合法范围，就可以放心地把它用在位图统计、定长记录更新等场景中，获得比整体读写更优的性能表现。
Redis SETRANGERedis字符串Redis命令修改时间：2026-08-31 06:46:32