PHP验证码生成教程｜GD库实现步骤详解

本文深入剖析了PHP中使用GD库生成验证码时最常遇到的四大“隐形陷阱”——GD扩展未启用、中文显示异常、图片被浏览器缓存、session未正确启动或写入，并逐一给出精准排查方法和可落地的解决方案：从跨平台启用GD扩展的命令与配置，到用imagettftext配合UTF-8字体和绝对路径正确渲染中文；从强制禁用缓存的HTTP头设置，到session_start()前置调用与验证码值及时存储的关键时机控制。这些不是理论细节，而是开发者在macOS、PHP 8.1+及各类部署环境中真实踩坑后提炼出的救命要点——少一个，验证码就静默失效，而错误往往悄无声息。

GD 扩展没启用，imagecreate 直接报错

很多本地环境（尤其是 macOS 或新版 PHP 8.1+）默认不启用 GD，调用 imagecreate 会直接抛出 Call to undefined function imagecreate()。不是代码写错了，是扩展根本没加载。

• Linux/macOS：运行 php -m | grep gd 看是否在列表里；没输出就需装扩展（Ubuntu 用 sudo apt install php-gd，macOS Homebrew 装 php@8.2-gd 类似）
• Windows：检查 php.ini 中 extension=gd 是否取消注释，且对应 php_gd2.dll 文件存在
• 重启 Web 服务（sudo systemctl restart apache2 或 brew services restart php），光重启 PHP-FPM 不够

imagestring 显示中文全是方块或乱码

GD 默认只支持 ASCII 字符，imagestring 压根不能画中文。imagettftext 是唯一靠谱方案，但字体路径、编码、坐标偏移三者必须对齐。

• 字体文件必须是真实存在的 .ttf 文件（推荐 Noto Sans CJK / simhei.ttf），路径用 __DIR__ . '/font/msyh.ttc' 这种绝对路径，别用相对路径或 URL
• 传入的中文字符串必须是 UTF-8 编码，如果来源是 GET 参数，先 mb_convert_encoding($_GET['t'], 'UTF-8', 'GBK') 转下
• imagettftext 的 Y 坐标是文字基线位置，不是顶部，设成 $height - 5 容易切字，建议用 imagettfbbox 测高后动态算

验证码图片被浏览器缓存，刷新不变

浏览器看到相同 URL 就复用缓存图片，用户点刷新按钮毫无反应——这不是逻辑问题，是 HTTP 头没控制好。

• 生成图片前必须加三行头：header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0');、header('Pragma: no-cache');、header('Expires: 0');
• 别只靠加随机参数（如 ?t=123）糊弄，有些代理或 CDN 会忽略 query string 缓存图片
• 如果用 AJAX 加载验证码，记得给 img.src 赋值时拼上时间戳，比如 img.src = '/captcha.php?t=' + Date.now()

session 存储验证码值，但 $_SESSION 取不到

GD 画完图后要立刻把验证码写进 session，但很多人忘了 session_start()，或者在输出图片前写了 echo 导致 headers already sent 错误。

• 脚本开头第一行必须是 session_start()，不能有任何空格、BOM、HTML 或 echo
• 验证码值要在 imagepng() 或 imagejpeg() 之前存，否则响应已发，session 写不进去
• 注意 session 生命周期：如果用户长时间没提交表单，$_SESSION['captcha'] 可能已过期，后端校验时得加空值判断

GD 生成验证码本身不难，真正卡住人的永远是环境、编码、缓存、会话这四块板子。少一个，页面就静默失败，连错误都不报。

到这里，我们也就讲完了《PHP验证码生成教程｜GD库实现步骤详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！