ThinkPHP 6+ 必须通过 Composer PSR-4 显式配置第三方类库路径，否则自动加载失效；需在 composer.json 中正确声明命名空间与目录映射，运行 composer dump-autoload -o 并验证 class_exists() 返回 true。
ThinkPHP 引入第三方类库报“Class not found”，90% 不是文件没放对，而是自动加载机制根本没覆盖到那个类。核心就一点：ThinkPHP 6+ 完全依赖 Composer 的 PSR-4 自动加载，它不会主动扫描 extend/、Library/ 或任意你放的目录——除非你明确告诉它“这个命名空间 → 这个路径”。
确认是否走通 Composer 自动加载
这是最常被跳过的一步。TP 启动时只认 vendor/autoload.php 里注册的映射，其他路径默认忽略。
- 检查 public/index.php 第一行是否为：require __DIR__ . '/../vendor/autoload.php';（路径不能错，比如项目嵌套深了，要改成 '../../vendor/autoload.php'）
- 运行 composer dump-autoload -o（加 -o 生成优化版映射），改完 composer.json 或新增类后必须执行
- 用命令行验证 autoload 是否生效：php -r "var_dump(class_exists('Your\Namespace\ClassName'));"，返回 true 才算真正加载成功
第三方 SDK 放在 extend/ 目录的正确做法
extend/ 只是约定存放地，不是自动加载源。直接丢进去，Composer 根本看不见。
- 不要用 require_once './extend/wechat/WxPayApi.php' —— 破坏自动加载，IDE 无提示，后续无法继承或类型校验
- 在 composer.json 的 "autoload": {"psr-4": {}} 中添加映射，例如：
"WeChat\": "extend/wechat/src/" - 如果 SDK 没命名空间（或用下划线类名如 AopClient），改用 "files" 方式：
"autoload": {"files": ["extend/alipay/aop/AopClient.php"]}
检查命名空间与路径是否严格一致
PSR-4 要求零误差：大小写、斜杠方向、层级深度，全部必须完全匹配。
立即学习“PHP免费学习笔记（深入）”；
- 类文件路径 extend/wechat/src/Pay/JsApiPay.php，对应命名空间必须是 namespace WeChatPay;（不能是 wechatpay 或 WeChat/Pay）
- Linux 服务器区分大小写：IndexController.php ≠ indexcontroller.php，Windows 开发没问题，一上服务器就崩
- composer.json 中的 PSR-4 映射末尾带反斜杠，如 "WeChat\": "extend/wechat/src/"，少一个 或多一个 / 都会失效
临时绕过但不推荐的补救方式
仅用于快速验证或紧急上线，不建议长期使用。
- 在 public/index.php 中框架初始化前（即 new App() 之前），手动注册：
thinkLoader::addNamespace('WeChat', __DIR__ . '/../extend/wechat/src'); - 确保该语句在 require '../vendor/autoload.php' 之后、new thinkApp() 之前
- 注意：Loader::addNamespace() 是 ThinkPHP 运行时机制，不参与 Composer autoload，也不被 IDE 识别
