在Redis的实际使用中，我们经常给键设置过期时间，比如缓存数据十分钟自动失效、验证码五分钟后删除。查询一个键还剩多久过期，大多数人第一反应是用TTL命令，但TTL返回的是秒数，精度只有秒级。如果业务上需要更精细的时间控制，比如限流窗口精确到100毫秒、分布式锁的续期判断，就需要用到PTTL这个命令。PTTL以毫秒为单位返回键的剩余生存时间，是Redis 2.6之后提供的核心时间命令之一。
PTTL命令的基本用法与返回值含义
PTTL的语法非常简单，只需要传入键名即可：PTTL key。它返回的结果有三种情况，理解这三种返回值是正确使用PTTL的基础。
第一种情况，如果键存在并且设置了过期时间，PTTL返回从当前时刻到键过期时刻之间的毫秒数。例如返回30000，表示这个键还剩30秒就会被Redis自动删除。第二种情况，如果键存在但没有设置过期时间，PTTL返回-1，表示这个键永远不会过期。第三种情况，如果键本身不存在，PTTL返回-2，注意这与-1的含义完全不同，很多初学者把-2当成异常值忽略了，导致业务逻辑判断出错。
redis> SET session:1001 "user-data" PX 60000 OK redis> PTTL session:1001 (integer) 59000 redis> PTTL not-exist-key (integer) -2 redis> SET config:main "stable" OK redis> PTTL config:main (integer) -1
在使用脚本或编程语言处理返回值时，一定要把负数单独判断。下面是一段Python示例，展示了规范的判断流程：
import redis
r = redis.Redis(host='127.0.0.1', port=6379, decode_responses=True)
def check_key(key):
pttl = r.pttl(key)
if pttl == -2:
return f"键 {key} 不存在"
elif pttl == -1:
return f"键 {key} 存在但没有设置过期时间"
else:
return f"键 {key} 剩余 {pttl} 毫秒（约 {pttl/1000:.1f} 秒）"
r.set("lock:order:88", "holder-1", px=5000)
print(check_key("lock:order:88"))
print(check_key("config:main"))PTTL与TTL、PEXPIRE、PSETEX的关系
PTTL并不是孤立存在的命令，它和一组以P开头的毫秒级命令构成了Redis的精确时间体系。TTL和PTTL是一对，前者返回秒、后者返回毫秒；EXPIRE和PEXPIRE是一对，前者以秒为单位设置过期时间、后者以毫秒为单位设置；SET EX和SET PX是一对，作用类似。这个对应关系可以用一张表来梳理。
| 功能 | 秒级命令 | 毫秒级命令 |
|---|---|---|
| 设置过期时间 | EXPIRE key seconds | PEXPIRE key milliseconds |
| 查询剩余时间 | TTL key | PTTL key |
| 设置值的同时指定过期 | SET key val EX s | SET key val PX ms |
| 查看过期时间戳 | EXPIRETIME key | PEXPIRETIME key |
有一个容易被忽略的细节：TTL的返回值并不是简单的PTTL除以1000后四舍五入。Redis源码中TTL会将毫秒值向上取整转换为秒，也就是说当PTTL返回1毫秒时，TTL会返回1而不是0。反过来，当你用PEXPIRE设置了一个1500毫秒的过期时间，紧接着用TTL查询会得到2，用PTTL查询会得到接近1500的数值。所以在需要精确计算的业务中，查询和设置都应该统一使用毫秒级命令，避免混用造成精度损失。
另外要提一下PSETEX，它是早期专门用于以毫秒为单位设置字符串值并附带过期时间的命令，功能上等价于SET key value PX milliseconds。新代码中推荐直接使用SET加PX参数，语义更清晰，而查询剩余时间统一交给PTTL即可。
PTTL的典型应用场景与注意事项
第一个典型场景是分布式锁的续期判断。使用Redis实现分布式锁时，客户端通常持有一个带过期时间的锁键，在执行业务逻辑前可以用PTTL检查剩余时间，如果发现剩余时间不足以完成后续操作，就主动续期（通过PEXPIRE重置过期时间）或者干脆放弃任务，避免锁提前失效导致多个客户端同时进入临界区。
// 伪代码：执行长任务前检查锁的剩余时间
long remain = jedis.pttl("lock:task:42");
if (remain > 0 && remain < 2000) {
// 剩余时间不足2秒，续期10秒
jedis.pexpire("lock:task:42", 10000);
}
// 继续执行业务逻辑...第二个场景是限流窗口的计算。比如实现一个每100毫秒最多允许N次请求的滑动窗口，可以把窗口键的过期时间设为100毫秒，每次请求时用INCR计数，再用PTTL获取剩余毫秒数告知客户端下次可请求的时间点，实现平滑的限流提示。
使用PTTL时有几个注意事项值得强调。其一，PTTL返回的值是命令执行瞬间的快照，网络延迟和后续操作都会让真实剩余时间产生偏差，因此不要把PTTL的返回值当作绝对准确的时间，在做关键判断时预留安全余量。其二，如果键在PTTL执行前恰好被删除或过期，返回-2是正常现象，代码要能优雅处理。其三，在Redis Cluster环境下，PTTL会根据键自动路由到对应节点，不存在跨节点问题，但在Lua脚本中批量对大量键调用PTTL时，要确保所有键分布在同一个哈希槽内，否则脚本会报错。其四，PTTL作用于整个键，对哈希、列表等复杂数据结构同样适用，但无法只查询某个字段级别的过期时间（字段级TTL需要Redis 7.4之后的版本支持）。
总结一下，PTTL配合PEXPIRE、SET PX等毫秒级命令，构成了Redis精确时间控制的完整工具链。在缓存管理、分布式锁、限流等对时间敏感的场景中，养成用PTTL代替TTL的习惯，能让系统的时间控制精度提升到毫秒级别，同时注意-1与-2的语义区分和返回值的时间快照特性，就可以稳定地将其应用到生产环境中。
Redis PTTLRedis TTLRedis过期时间修改时间：2026-09-05 16:10:46