thinkphp验证码包安装必须严格匹配框架版本：tp6用topthink/think-captcha（不指定版本），tp5.0用=1.，tp5.1用=2.；安装前需运行php think version确认版本，再在项目根目录执行对应composer require命令，并启用session、执行php think captcha:install发布资源。
验证码包安装要匹配框架版本
ThinkPHP不同主版本对验证码扩展包的兼容性要求严格，装错版本会导致类找不到或方法报错。TP6项目必须用 topthink/think-captcha（不指定版本号），TP5.0只能用 =1.*，TP5.1则需 =2.*。安装前先运行 php think version 确认框架版本，再进项目根目录执行对应命令。Windows和Linux下命令一致，但要注意路径权限——Linux需确保 vendor/ 目录可写，Windows则留意防病毒软件可能拦截自动加载文件生成。
.env 与 Session 是跨平台校验失效的主因
验证码校验失败，90%不是代码问题，而是环境支撑断了。在 Windows 和 Linux 上都必须确认两件事：
一是 APP_DEBUG=true 且 .env 文件位于项目根目录（和 think 可执行文件同级），否则框架根本不会加载它，数据库、缓存、短信密钥等配置全走默认值；
二是 Session 必须显式启用——TP6 默认注释了 \think\middleware\SessionInit::class，需在 app/middleware.php 中取消注释。Linux 下还要检查 runtime/session 是否可写，Windows 下注意 IIS 或 Nginx 的 PHP 进程用户是否有写入权限。
资源发布与前端路径需手动标准化
执行 php think captcha:install 后，Linux 和 Windows 对路径分隔符的处理差异会暴露出来：Windows 生成的路径含反斜杠，某些前端引用逻辑在 Linux 下会 404。建议统一用正斜杠，并在部署后检查：
• public/static/captcha/ 目录是否存在且含 captcha.js、captcha.css 和 images/
• 浏览器开发者工具 Network 面板中，验证码图片请求是否返回 200，URL 是否为 /static/captcha/xxx.png 而非带盘符或双斜杠的异常路径
• 若用 Nginx，确认 location ~ ^/static/ 规则未错误拦截静态资源
短信验证码要避免 Session 绑定陷阱
图形验证码依赖 Session 没问题，但短信验证码若也存进 session('sms_code')，跨平台上线就容易崩：Windows 开发时一个浏览器能复用，Linux 生产环境换子域、换服务器、清缓存后 Session ID 就变了。更稳妥的做法是：
• 存储改用缓存键： cache('sms_' . $phone, $code, 300)（5 分钟过期）
• 校验时直接读缓存，不依赖 session_id
• 密钥从环境变量读取，Linux 用 export ALIYUN_ACCESS_KEY_SECRET=xxx，Windows 用 set ALIYUN_ACCESS_KEY_SECRET=xxx，Docker 则通过 environment: 注入
• 发送环节推荐 overtrue/easy-sms，它自动处理重试、异常捕获和多通道切换，比手写 curl 稳定得多
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
