Xiuno 验证码不显示？五分钟全搞定秘籍

52JinY 助手

最近在折腾老论坛，踩了个挺典型的坑：xiuno 验证码不显示。看似小问题，其实牵扯到环境、扩展、权限一串因素。我把自己排查的思路和结论整理一下，或许能帮到同样卡住的人。

先说现象：发帖/注册处验证码区域空白，有的只有一个小叉图片，有的直接不渲染 DOM。这个时候别急着重装插件，先打开浏览器控制台看网络请求。xiuno 的验证码一般走一个 captcha 或 image 接口，看看该请求是不是 404、500 或跨域被拦了。如果是 404，多半是伪静态或路由没匹配；500 则进一步看服务端错误日志。

环境层面，PHP 扩展是第一嫌疑。xiuno 常用的验证码实现依赖 GD 或 imagick。很多人迁移到新服务器忘了装 php-gd，结果图片生成失败。用 phpinfo() 或命令行 php -m 查一下有没有 gd；没有就安装并在 php.ini 启用，重启 FPM/Apache。Imagick 同理，但就稳定性和

资源占用来说，GD 更轻量，也更常见。装好扩展后别忘了检查字体依赖，验证码通常要用到 TTF 字体渲染，服务器上缺少对应字体文件或路径配置错误，也会导致生成失败。xiuno 的一些验证码脚本里会写死一个 fonts/xxx.ttf 的相对路径，迁移时路径变了就找不到。解决办法是把字体文件放到预期目录，或者在代码里改成绝对路径。

权限问题也很隐蔽。部分版本会把验证码图片以文件形式写入临时目录，再输出给前端。如果 runtime、tmp、upload 这些目录没有写权限，脚本报错但前端只看到空白。简单粗暴地给目录 755/775（必要时 777 仅用于定位问题）试一下，确认写权限没问题后再收紧。顺带检查 SELinux/AppArmor 有没有拦截 PHP 写文件或调用系统字体。

再说 Nginx/Apache 配置。反代或 CDN 在前时，某些路径可能被缓存或拦截，尤其是带 query 的图片请求。如果你给静态资源上了强缓存，但验证码接口被误判为静态文件，用户会拿到旧图或空图。给验证码接口加 no-cache 头，或者在 Nginx 里对 /captcha、/image 这类路径禁用缓存。另外，站点从 http 升到 https 后，混合内容会被浏览器拦截，控制台会提示 blocked:mixed-content。确保站内 URL 统一用 https，后台配置和 config.php 的 base_url 要一致。

版本兼容也别忽略。xiuno 核心和插件混搭时，老的验证码插件可能调用了废弃函数，比如老 PHP 7 的写法在 PHP 8 上直接 fatal。看一眼 php-fpm 的 error_log，若见到类似 “Deprecated function” 或 “Call to undefined function imagecreate()”，就对症下药：要么回退 PHP 版本到 7.4，要么更新/替换插件。实在找不到可用插件，干脆改成更通用的方案，比如简单的算术验证码，依赖更少。

跨域和安全头也会出手。前后端域名不一致时，验证码接口被 CORS 拦下，或者 CSP 过严禁止内联图片/数据 URI。检查响应头里的 Access-Control-Allow-Origin、Content-Security-Policy，先临时放宽验证路径，再逐步收紧规则到最小集。还有一种情况是 Referer 校验过严，CDN/防火墙把接口当成异常流量拦截，WAF 日志里能看到痕迹。

如果你是从备份恢复或搬家后才发生，重点看路径和 session。验证码通常会把答案写进 session，若你把 session.save_path 指到一个不可写目录，或多节点下没做共享，前端拿到的图片和后端校验不同步，表现就是“看得到但永远校验失败”。单机先确认 session 正常写入，多机要用 Redis/Memcached 做会话共享。

最后给个最小化自检清单：1) php -m 确认 gd/imagick 在列；2) phpinfo() 看字体、GD 版本；3) Nginx/Apache 日志和 php-fpm 错误日志是否有 500/致命错误；4) 验证码接口直接在浏览器打开，确认 HTTP 状态码和响应头；5) 目录权限与 SELinux 状态；6) 关闭 CDN 缓存或绕过规则测试；7) PHP/插件版本对齐；8) session 是否可用。

我的实践里，十之八九是 GD 未装或权限/路径问题。排查时别被前端现象迷惑，沿着“请求是否到达—代码是否运行—资源是否可写—响应是否被缓存/拦截”这条链路，一节节打通，基本都能很快定位。解决后记得补一段监控和日志告警，下次升级/迁移时就不会再踩同一个坑了。