应根据项目需求选择版本：新项目需小程序云开发用v6.x，常规公众号功能用v5.6.x；PHP和Composer版本须匹配，配置需严格对应微信后台，初始化前确保session启动、回调地址精确一致，IP白名单与JSAPI域名必须配置。
直接用 composer require overtrue/wechat 就能装，但多数人卡在「装了调不通」——根本原因是版本、配置和初始化方式没对上，不是 SDK 本身有问题。
为什么 composer require overtrue/wechat 装完就报错？
常见错误是 Class 'EasyWeChatFactory' not found 或 Target class [overtrue/wechat] does not exist，本质是 Composer 自动加载没生效，或用了不兼容的 PHP/Composer 版本。
- PHP 必须 ≥ 7.2（v5.x SDK）或 ≥ 8.0（v6.x SDK），运行
php -v确认 - Composer 版本建议 ≥ 2.0；若用
composer install报 autoload 错误，先执行composer dump-autoload -o - v6.x 开始弃用
EasyWeChatFactory，改用Overtrue\WeChat\Kernel\ServiceContainer，老教程代码会直接失效
如何选对版本并正确 require？
别无脑 latest。微信开放平台接口变动频繁，v6.x 对 OAuth、JS-SDK、消息解密等做了重构，但文档滞后，v5.x 反而更稳。
- 新项目且需小程序云开发、多公众号复用：用 v6.x —— 运行
composer require "overtrue/wechat:^6.0" - 对接公众号网页授权、模板消息、客服消息等常规场景：v5.6.x 更省心 ——
composer require "overtrue/wechat:5.6.*" - laravel 项目建议搭配
overtrue/laravel-wechat，它自动处理服务提供者注册，避免手动写config/wechat.php
配置文件怎么写才不踩坑？
很多人把 app_id 写错位置，或混淆了「公众号」和「开放平台第三方代管」的配置结构。
- v5.x 的
config/wechat.php中，'app_id'是公众号的 AppID，'secret'是对应的 AppSecret；若走开放平台代公众号授权，要额外配'open_platform'数组，含'component_app_id'和'component_app_secret' - v6.x 配置扁平化，所有参数传进
ServiceContainer构造函数，不再依赖全局 config 文件；但oauth' => ['scopes' => ['snsapi_base']]这类嵌套键名容易漏掉引号，导致 scope 不生效 - 敏感字段如
token、aes_key必须严格按微信后台填写，大小写、长度、末尾换行都影响签名验证
初始化后为什么 getOAuth()->redirect() 404 或跳转空白？
这不是 SDK 问题，而是路由、回调地址、session 配置三者没对齐。
- Laravel 用户注意：
session_start()必须在 redirect 前触发，否则 OAuth state 无法存储；推荐用中间件确保 session 已启动 - 回调地址（
redirect_uri）必须和微信后台「公众号设置 → 网页授权获取用户基本信息」里填的一致，协议、域名、端口、路径全部精确匹配，不能带www.或/index.php - v6.x 的
getOAuth()返回的是Overtrue\WeChat\OpenPlatform\OAuth实例（开放平台）还是Overtrue\WeChat\OfficialAccount\OAuth（公众号），取决于你 new 的是哪个容器，混用会抛出未定义方法异常
最常被忽略的是微信后台的 IP 白名单和 JSAPI 安全域名——哪怕 SDK 初始化和请求全对，这两个没配，JS-SDK 的 config 接口也会静默失败，控制台只报 invalid signature，跟代码无关。
