ThinkPHP 引入第三方类库报 Class not found 的核心原因是自动加载机制未识别类，需确认是否正确引入 vendor/autoload.php、检查 composer.json 的 PSR-4 映射、执行 composer dump-autoload -o 刷新，或按规范存放并匹配命名空间与路径。
ThinkPHP 引入第三方类库报 Class not found，绝大多数情况不是文件没放对、也不是代码写错了，而是自动加载机制压根没“认出”这个类。核心矛盾在于：框架不会主动扫描所有 PHP 文件，它只按规则找——规则错了，哪怕文件真实存在，也等于不存在。
确认是否走 Composer 自动加载路径
ThinkPHP 6+ 完全依赖 Composer 的 autoload 机制，入口文件必须第一行引入 vendor/autoload.php；否则整个自动加载链就断了。
- 检查
public/index.php（或其他入口）开头是否有：require __DIR__ . '/../vendor/autoload.php'; - 如果用的是手动复制 SDK 到
extend/或vendor/子目录，但没在composer.json中声明 PSR-4 映射，Composer 就完全无视它 - 执行
composer dump-autoload -o强制刷新映射，尤其在改过composer.json或新增类目录后
第三方 SDK 放在哪、怎么注册才有效
不能“随便一丢就完事”。不同存放位置对应不同加载方式，混用就会失效：
- 推荐方式：用
composer require vendor/name正规安装 → Composer 自动注册命名空间，无需额外操作 - 若 SDK 没发布到 Packagist，需手动加 PSR-4 映射：
在composer.json的"autoload": {"psr-4": {...}}中添加，例如："lib\": "extend/lib/"→ 对应extend/lib/WeChatPay.php的命名空间必须是namespace lib; - 直接拖进
extend/但不想配 composer.json？可用 ThinkPHP 的命名空间自动注册功能：
确保目录结构与命名空间严格一致（如extend/qrcode/QrCode.php→namespace qrcode;），然后直接new qrcodeQrCode()
不走 Composer 时的备选方案
有些老 SDK 没命名空间、没遵循 PSR 规范，或者你就是想快速测试，这时可绕过自动加载：
立即学习“PHP免费学习笔记（深入）”；
- 用
import()助手函数（TP5/6 支持）：import('qrcode.qrcode', EXTEND_PATH, '.php');→ 对应extend/qrcode/qrcode.php - 用
vendor()（主要面向 TP3.2，TP6 已不推荐）：
仅适用于放在thinkphp/library/Vendor/下的老式类库，且文件名需为xxx.class.php格式 - 最直白但需谨慎：用原生
require_once，路径务必写绝对路径或基于__DIR__计算，避免相对路径跨控制器失效
高频踩坑点速查
很多问题其实就卡在一两个细节上：
-
大小写敏感：Linux 服务器下，
wechatpay.php≠WeChatPay.php，类名、文件名、命名空间三者字母大小写必须完全一致 -
命名空间与路径不匹配：比如
namespace appservice;就必须放在app/service/Alipay.php，少一层或多一层都会失败 -
IDE 没报错但运行报错：可能是 runtime 缓存或 classmap 没更新，清空
runtime/cache/和runtime/container/后重启请求 -
用了
use却忘了反斜杠：如new Alipay();而不是new Alipay();（后者会拼上前置命名空间）
