Redis的哈希类型提供了一条专门用于条件写入的命令HSETNX。它的语义非常明确：只有当指定的字段在哈希表中不存在时，才会把值写入该字段；如果字段已经存在，命令不会覆盖原有值，而是返回0表示操作未执行。这个命令的全称是Hash Set If Not eXists，从命名上就能看出它与字符串键的SETNX一脉相承。
理解HSETNX的关键在于“字段不存在”这个条件。它判断的是哈希表内部字段槽位是否被占用，而不是字段值是否为空字符串。也就是说，只要字段之前被写入过，哪怕值是空字符串""，HSETNX也会返回0。如果要让该字段重新变成可写入状态，需要先使用HDEL删除字段。
一、HSETNX的基本用法与返回值
HSETNX命令的语法非常简洁，格式为HSETNX key field value。其中key是哈希表的键名，field是要操作的字段名，value是要写入的值。如果字段不存在，Redis会创建该字段并写入值，返回整数1；如果字段已经存在，则不会做任何修改，返回整数0。
下面通过redis-cli演示一次完整的调用过程。先对一个用户哈希表设置姓名字段，第一次执行时字段不存在，返回1；第二次执行时字段已经存在，返回0，并且原有值保持不变。
127.0.0.1:6379> HSETNX user:1001 name Alice (integer) 1 127.0.0.1:6379> HSETNX user:1001 name Bob (integer) 0 127.0.0.1:6379> HGET user:1001 name "Alice"
从这个例子可以看出，第二次尝试写入Bob并没有覆盖掉Alice。HSETNX只关心字段是否存在，与值的内容无关。即使字段当前的值是空字符串，只要字段存在，调用仍然返回0。如果需要修改已有字段的值，应该使用HSET命令。
HSETNX的时间复杂度为O(1)，因为哈希表的字段查找和写入在平均情况下都是常数时间。它作用于Redis的哈希类型，不能用于字符串、列表、集合等其他数据结构。如果键不存在，Redis会先创建一个空哈希表再执行字段写入，因此第一次对不存在的键执行HSETNX也能成功。
二、HSETNX与先检查再设置的对比
在没有使用HSETNX之前，很多实现条件写入的逻辑是先调用HEXISTS检查字段是否存在，再根据结果决定是否执行HSET。这种写法在单线程客户端串行执行时没有问题，但在并发场景下会暴露竞态缺陷。
假设两个客户端同时检查某个字段是否存在，双方都得到“不存在”的结果，随后都执行HSET写入自己的值。最终后写入的值会覆盖先写入的值，而业务上可能希望只有第一个客户端能写入成功。这就是典型的检查再设置竞态。
HSETNX将判断和写入合并成一条命令，Redis单线程会串行执行每条命令，因此判断与写入之间不会被其他命令插入。客户端只需要根据返回值是1还是0就能确定自己是否抢到了写入权，不需要额外的锁或事务。
127.0.0.1:6379> DEL config (integer) 1 127.0.0.1:6379> HEXISTS config theme (integer) 0 127.0.0.1:6379> HSET config theme dark (integer) 1
上面的操作如果在并发环境中执行，HEXISTS返回0之后、HSET执行之前，另一个客户端可能已经写入了theme字段。此时后执行的HSET会覆盖掉对方的值，业务逻辑被破坏。如果用HSETNX替代，第二个客户端尝试时会得到0，从而避免覆盖。
从性能角度看，HSETNX只需要一次网络往返和一次命令执行，而先检查再设置至少需要两次网络往返。在高并发写入场景中，减少一次往返可以明显降低延迟和Redis负载。
三、HSETNX的原子性保证与典型应用场景
HSETNX的原子性来源于Redis的单线程命令执行模型。Redis服务端在同一时刻只会处理一条命令，HSETNX内部的查找字段和写入字段是连续完成的，不会被打断。因此，多个客户端同时发起HSETNX，最终只有一个会返回1，其余都会返回0。
这种特性非常适合实现分布式锁中的持有者记录。比如多个服务实例竞争某个资源时，可以把锁信息写入一个共享哈希表，使用HSETNX尝试设置锁标识字段。返回1表示获取锁成功，返回0表示锁已被占用。
127.0.0.1:6379> HSETNX lock:order:1001 owner client-A (integer) 1 127.0.0.1:6379> HSETNX lock:order:1001 owner client-B (integer) 0
在这个例子中，client-A成功写入了owner字段，client-B返回0，说明锁已经被别人持有。业务代码可以根据返回值决定是否继续执行后续逻辑。释放锁时使用HDEL lock:order:1001 owner删除字段即可。
除了分布式锁，HSETNX还常用于资源初始化、默认配置写入、幂等记录等场景。例如，第一次访问时写入某个用户配置的默认值，后续访问不再覆盖用户自定义配置；或者用哈希表记录某个事件是否已处理，使用HSETNX实现幂等标记。
需要注意的是，HSETNX本身不能同时设置过期时间。如果用于分布式锁，还需要考虑锁的自动过期问题。通常的做法是在获取锁后使用PEXPIRE为整个哈希键设置过期时间，但这两步不是原子的。更可靠的方式是使用Lua脚本将HSETNX和PEXPIRE组合成原子操作。
四、常见误区与批量操作
使用HSETNX时，一个常见误区是认为它可以一次性设置多个字段。实际上HSETNX一次只能操作一个字段。如果需要批量写入多个字段且要求字段不存在时才写入，可以使用Redis事务或Lua脚本。
另一个误区是混淆字段存在与值是否为空。Redis哈希表中的字段存在与否由哈希表内部结构决定，与值的内容无关。即使字段的值是空字符串，HSETNX依然会返回0。只有使用HDEL删除字段后，HSETNX才能再次写入。
HSETNX与字符串键的SETNX虽然名字相似，但作用对象不同。SETNX用于设置字符串键的值，而HSETNX用于设置哈希表内的字段值。两者都是条件写入命令，但不可混用。
对于批量条件写入，推荐使用Lua脚本。Redis会以原子方式执行整个Lua脚本，脚本内部的每个HSETNX都会依次判断并设置。下面是一个批量设置多个字段的示例。
-- 批量设置字段，仅当字段不存在时写入
-- KEYS[1] 是哈希键，ARGV 成对出现，第一个是字段名，第二个是值
for i = 1, #ARGV, 2 do
redis.call('HSETNX', KEYS[1], ARGV[i], ARGV[i + 1])
end
return redis.call('HGETALL', KEYS[1])
在实际使用中，Lua脚本内部多次调用HSETNX仍然保持原子性，不会出现部分字段写入成功、部分失败的情况。如果业务逻辑要求所有字段要么全部写入要么全部不写入，可以在脚本开头使用循环检查所有字段是否存在，确认全部不存在后再统一写入。
还需要注意，HSETNX在Redis 2.0.0及以上版本中提供，但早期版本中可能存在性能或兼容性差异。部署前应确认Redis版本是否支持该命令。另外，如果哈希键包含大量字段，批量操作可能阻塞Redis，建议控制每次操作的字段数量或使用异步队列。
Redis HSETNX哈希字段原子操作修改时间：2026-09-26 07:14:04