TP5.1/5.2项目必须安装overtrue/wechat:~5.0并确保autoload.php被引入；TP6项目必须用easywechat/easywechat:^6.0，因overtrue/wechat已归档且PHP8+兼容问题；serve()需独立入口调用，配置token/aes_key须严格校验长度与空白字符。
直接上结论：TP5.1+ 项目别装 overtrue/wechat:~4.0，TP6 项目必须用 easywechat/easywechat:^6.0；装错版本或漏掉自动加载，Factory::officialAccount() 会报类找不到，不是配置问题，是根本没加载进 PHP。
TP5.1/5.2 怎么装 easywechat 才不报 Class 'EasyWeChat\Factory' not found
这是最常卡住的点——TP5.1 虽然支持 Composer 自动加载，但默认没启用 PSR-4 映射，且 overtrue/wechat 5.x 的命名空间结构和 TP5.1 的加载器有兼容边界。
- 必须安装
overtrue/wechat:~5.0（不是 4.x，也不是 latest），命令带引号：composer require "overtrue/wechat:~5.0" - 确认
public/index.php开头有：require __DIR__.'/../vendor/autoload.php'; - 如果用了 ThinkPHP 的多模块或自定义命名空间，别把
use EasyWeChat\Factory;写在控制器方法里，要放在类顶部use区 - 执行
composer dump-autoload -o强制刷新映射，尤其改过composer.json后
TP6 项目为什么 composer require overtrue/wechat 会失败
因为 overtrue/wechat 官方已归档，不再维护，TP6 默认启用 PHP 8+ 严格类型检查，其 5.x 分支在 PHP 8.1+ 下会触发 ReturnTypeWillChange 报错；Packagist 上 overtrue/wechat 已标记为 abandoned。
- TP6 必须用新官方主干：
composer require "easywechat/easywechat:^6.0" - 它的命名空间是
EasyWeChat\Kernel\Messages\Text，和 5.x 一致，迁移成本低 - 别信教程里“TP6 也能用 5.x”，实测在 PHP 8.2 环境下
AccessToken刷新会因反射调用失败而卡死 - 安装后检查
vendor/easywechat/easywechat/src/是否存在，若为空，说明镜像源没切对——优先用腾讯源：composer config -g repos.packagist composer https://mirrors.tencent.com/composer/
app()->server->serve() 在 TP 路由里空白或 500 怎么办
TP 框架的中间件、输出缓冲、路由调度机制会干扰 serve() 的原始 HTTP 响应流程。它不是普通业务逻辑，而是要接管整个请求生命周期。
- 不要在控制器方法里调
$app->server->serve()，它内部会exit，导致 TP 的响应结束逻辑崩溃 - 放到独立入口脚本更稳，比如
public/wx.php，内容只有三行：require __DIR__.'/../vendor/autoload.php'; $app = \EasyWeChat\Factory::officialAccount($config); $app->server->serve()->send(); - 若坚持走 TP 路由，必须关掉所有中间件（包括
CheckRequestCache、Token），并在路由定义中显式指定['middleware' => []] - 确保 Web 服务器没截断 POST 数据：Nginx 需设
client_max_body_size 10M;，Apache 需确认LimitRequestBody未设为 0
配置数组里 token 和 aes_key 总是 signature invalid
微信签名验证失败，90% 不是代码问题，是配置字符串本身被污染了——PHP 不报错，但微信服务器校验时直接拒收。
-
token必须和公众号后台「服务器配置」里填的**完全一致**，包括大小写、空格、不可见字符；建议从后台复制后套一层trim()：'token' => trim(Config('wx.token')) -
aes_key是 43 位 Base64 字符串，复制时容易带换行或末尾空格；用strlen($config['aes_key']) === 43校验长度，不匹配就重填 - 别把
secret当成token传——前者用于拉取 access_token，后者仅用于签名生成，二者用途完全不同 - 测试阶段先禁用消息加密（后台不填
aes_key），等明文通了再开，避免两层错误叠加
真正难调试的从来不是 SDK 调用，而是 token 多一个空格、vendor/autoload.php 没被 require、或者 ngrok 映射 URL 没填进公众号后台——这些地方没日志、不报错、只静默失败。
