ThinkPHP部署后接口幂等失效的三大根源：一、缓存驱动未切Redis，仍用file/array导致多进程/多机失效；二、幂等TTL设置不当，过短致重复执行、过长致误拦截；三、指纹含timestamp等动态字段，导致每次计算结果不同。
ThinkPHP部署后接口幂等失败，核心问题往往不在“有没有做”，而在于幂等控制的实现方式与生产环境不匹配。常见表现是：本地测试正常，上线后重复请求仍被处理（如重复下单、重复扣款），或反过来——误拦截合法请求。
下面从三个高频踩坑点切入，直击部署后失效的根源：
一、缓存驱动没切到 Redis，还在用 file 或 array
ThinkPHP 默认缓存驱动是 file，它在多进程/多服务器环境下完全不可靠：
- 不同 PHP-FPM worker 进程写各自的缓存文件，
Cache::has()查不到其他进程设的锁； - 负载均衡下多台机器更彻底失效，指纹标记形同虚设。
✅ 正确做法：
立即学习“PHP免费学习笔记（深入）”；
- 确保
config/cache.php中'default' => 'redis'； - Redis 配置需启用
host、port、password（如有），且网络可达（可telnet redis-host 6379测试）； - 检查
cache.redis.prefix是否设置合理（避免不同环境 key 冲突）。
二、幂等窗口期（TTL）设置不合理
本地开发常设 300 秒，但生产环境若用短连接或高并发重试密集，可能：
- TTL 太短（如 10 秒）：用户操作稍慢，重试时锁已过期，重复执行；
- TTL 太长（如 3600 秒）：缓存堆积、内存溢出，还可能误拦后续合法请求（比如用户 1 小时后重试同一笔订单）。
✅ 推荐值：
- 表单类接口（如下单、支付）：
120～180 秒（覆盖前端防抖+网络重试全周期）； - 回调类接口（如微信/支付宝异步通知）：
300 秒（第三方回调重试窗口通常 ≤ 5 分钟）； - 用
Cache::remember('idempotent_' . $fingerprint, $ttl, fn() => $result)替代手动has()+set()，规避竞态。
三、指纹生成逻辑包含动态字段，导致每次都不一样
典型错误：直接对 input() 全量 JSON 做 md5，却没过滤 timestamp、nonce、sign 等实时参数。结果：
- 同一笔支付请求，因时间戳差 1 秒，指纹完全不同，幂等锁根本不起作用。
✅ 安全做法：
- 提取业务本质参数：
user_id + uri + order_no + amount（支付类）或user_id + uri + product_id（下单类）； - 显式排除字段：
unset($params['timestamp'], $params['nonce'], $params['sign'])； - 对剩余参数按 key 排序后 JSON 编码再 hash，确保顺序一致：
ksort($safeParams); $fingerprint = md5($userId . $request->url() . json_encode($safeParams));
补充提醒：别把
Token::check()当幂等方案。它是一次性 token，验证即销毁；而幂等要求“相同请求多次进来只执行一次”。两者语义不同，混用会导致重试失败而非静默忽略。
不复杂但容易忽略。
