验证码路由必须显式声明{captcha_id:string}，VerifyString校验后须立即废弃并生成新ID，图片响应头需设Cache-Control等禁用缓存，前后端captcha_id字段名须严格一致。
验证码图片路由必须带 :string 类型参数
Iris 的 /captcha/{captcha_id} 这类路由，{captcha_id} 必须声明为 :string，不能写成 :id 或省略类型。Iris 路由引擎对未标注类型的路径段默认按 :string 处理，但显式写明更安全——因为 dchest/captcha 生成的 ID 是纯字母数字字符串（如 Q7X9R2T4），若误用 :int，请求会直接 404，连 BeforeActivation 都进不去。
常见错误现象：GET /captcha/abc123 返回 404，但日志里看不到任何处理痕迹。原因就是路由匹配失败，根本没走到控制器。
- 正确写法：
b.Handle("GET", "/captcha/{captcha_id:string}", "CaptchaImage") - 错误写法：
b.Handle("GET", "/captcha/{captcha_id}", ...)（依赖隐式推断，不稳） - 更错写法：
b.Handle("GET", "/captcha/{captcha_id:int}", ...)（ID 含字母，必挂）
captcha.VerifyString 校验后必须立即废弃原 captcha_id
dchest/captcha 库的 VerifyString 是单次有效的：一旦调用成功，该 captcha_id 对应的验证码答案就会从内存中清除。如果登录逻辑里校验通过后没重新生成新 ID，用户刷新页面或重复提交时，captcha_id 已失效，后续请求会始终返回“验证码错误”。
典型场景：用户输对验证码 → 登录成功 → 前端没清空表单 → 用户又点一次登录 → 后端用同一个 captcha_id 再次调用 VerifyString → 返回 false。
- 解决方法：校验通过后，立刻调用
captcha.NewLen(4)生成新 ID，并更新前端的CaptchaPath和uuid字段 - 不要复用旧 ID，哪怕只是“再试一次”也不行
- 注意：Redis 或内存存储层无法绕过这个限制——这是
dchest/captcha底层设计决定的
图片响应头必须禁用缓存，否则前端看到的是旧图
Iris 默认不会自动设置图片缓存头，而浏览器对 image/png 资源极其激进地缓存。用户点击“换一张”，URL 看似变了（/captcha/abc123 → /captcha/def456），但若响应头没明确禁止缓存，Chrome 可能直接从内存 cache 返回上一张图的二进制流，导致用户看到的永远是第一张图。
关键响应头缺一不可：
w.Header().Set("Cache-Control", "no-cache, no-store, must-revalidate")w.Header().Set("Pragma", "no-cache")w.Header().Set("Expires", "0")
漏掉任意一项，尤其 Cache-Control，在生产环境 iOS Safari 或某些企业内网代理下大概率出问题。
前端传参和后端取参要严格对应 captcha_id 字段名
登录表单提交时，必须把当前显示验证码的 captcha_id（不是图片 URL 中的 ID，而是生成时返回的那个字符串）和用户输入的文本一起发给后端。后端校验时，captcha.VerifyString(captcha_id, user_input) 的第一个参数必须是原始生成 ID，不能是 URL path 中截出来的子串，也不能是前端拼接过的。
容易踩的坑：
- 前端从
/pub/captcha/ABC123这个路径里用正则提取ABC123当 ID —— 看似合理，但若路径结构变更（比如加了前缀/v2/captcha/），就崩了 - 后端从
ctx.Params().Get("captcha_id")取值用于校验 —— 错！那是图片接口的参数，登录接口根本没这个 path 参数 - 正确做法：前端把生成时拿到的
captcha_id存进隐藏域或 Vuex/Pinia state，登录时作为普通表单字段（如captchaId）提交；后端用ctx.FormValue("captchaId")获取
这个映射关系断掉，校验必然失败，且错误信息毫无提示，只能靠断点看 captcha_id 是否为空或乱码。
