应使用 overtrue/wechat 而非 wechat；PHP≥7.2；本地开发需 ngrok 映射公网 URL；serve() 需放路由闭包中，勿被中间件拦截；接收消息靠 serve()->send()，非 push()；务必校验 token/aes_key/appid 与后台完全一致。
composer install 失败提示 “no matching package found”
微信官方没提供 wechat 或 wechat-sdk 这类通用包名，直接 composer require wechat 必然报错。国内主流用的是 overtrue/wechat（已维护多年，Laravel 生态常用），不是腾讯官方发布的包，但接口覆盖全、文档清晰、更新稳定。
- 装错包名是新手最常卡住的点，别搜“微信SDK composer”，直接认准
composer require overtrue/wechat - PHP 版本要 ≥ 7.2，低于这个版本会提示
class_exists(): Argument #1 ($class) must be of type string类似错误 - 如果项目用了 Laravel，
overtrue/wechat有配套的overtrue/laravel-wechat，但入门阶段建议先用基础版，避免框架封装掩盖底层逻辑
公众号配置后调用 app()->server->serve() 报 500 或空白页
微信服务器验证和消息接收必须走明文 HTTP（非 HTTPS）回调，但本地开发环境通常没配域名+SSL，直接在 localhost 调 serve() 会失败——因为微信服务器根本连不上你本地地址。
- 用
ngrok http 8000或localtunnel映射本地端口，拿到公网 URL 后填到公众号后台「服务器配置」里 -
serve()方法默认会自动响应微信的GET验证请求，但如果中间件拦截了 GET 请求（比如某些 Laravel 的 CSRF 中间件），会导致验证失败，页面空白 - 别在控制器里直接写
$app->server->serve()，它会自动输出并 exit，放在路由闭包或单独入口脚本里更可控
收不到用户消息，server->push() 没反应
微信服务器只把用户消息 POST 到你填的 URL，不会主动拉取；push() 是用于主动推送模板消息、客服消息等，和接收无关。混淆这两个方向是调试时最典型的误解。
- 接收消息靠
$app->server->serve()->send()，它会解析 POST 数据、校验签名、分发事件 - 如果收到消息但没触发事件回调，检查是否漏写了
$app->server->setMessageHandler()，或者 handler 返回值不是字符串（微信要求必须返回非空字符串，否则当失败处理） - 日志关了就等于瞎子：加一句
$app->server->setLogger(\Psr\Log\NullLogger::class)不如直接用error_log()打点关键变量，比如$_POST和$_GET内容
token / aes_key / appid 填错导致签名验证失败
微信所有通信都带签名，只要 token、encoding_aes_key（启用消息加密时才需要）、appid 三者中有一个和公众号后台不一致，serve() 就会直接返回空或 401，不会抛异常。
-
token是纯字符串，大小写敏感，不能带空格；后台填的是mytoken123，代码里写成MyToken123就验不过 -
encoding_aes_key是 43 位 Base64 字符串，复制时容易多一个换行或空格，建议用trim()包一层再传给 SDK - 公众号有测试号和正式号两套配置，测试号后台地址是
mp.weixin.qq.com/debug/cgi-bin/sandboxinfo?action=showinfo，别拿正式号的 appid 去配测试号环境
真正麻烦的不是装不上，而是装上了但收不到消息、验不过签、回不了包——这些地方没日志、没报错、只有沉默，得一个个抠参数、对路径、看微信后台的「接口分析」里的失败原因。
