composer install 失败因未指定正确包名，应使用 composer require "easywechat/easywechat:^6.0"；class not found 是 autoload 未生效，需确认 vendor/autoload.php 是否正确引入；oauth 跳转域名由配置中 redirect 决定，非代码传参；模板消息 invalid template_id 多因 id 复制错误或环境不匹配。
composer install 失败：找不到微信 SDK 包
微信官方没有提供 composer 官方包，社区主流用的是 overtrue/wechat（已停止维护）或其活跃分支 easywechat/easywechat。直接运行 composer require wechat 或 composer require wechat/php-sdk 必然报错：Could not find package wechat。
正确做法是明确指定包名和版本约束：
-
composer require "easywechat/easywechat:^6.0"（推荐，PHP 8.0+，Laravel 友好） -
composer require "overtrue/wechat:~4.4"（仅限老项目兼容，PHP 7.2+，不再更新）
注意：别漏掉引号，避免 shell 把 ^ 或 ~ 当作特殊字符解析；如果项目已禁用 Packagist 镜像，需先确认是否配置了国内源（如阿里云、腾讯云），否则拉取超时也会被误判为“找不到包”。
初始化 EasyWeChat 实例时报 Class 'EasyWeChatFactory' not found
这是自动加载失败的典型表现，不是代码写错了，而是 composer autoloader 没生效。常见于以下情况：
- 执行
composer install后没刷新 autoload（尤其在 Docker 或部署环境里忘了composer dump-autoload） - 用了
--no-autoloader参数安装，或者composer.json中"autoload"配置被意外清空 - 项目根目录下没有
vendor/autoload.php（比如你把vendor放到了别处，但没改 require 路径）
验证方式：在入口文件加一行 var_dump(class_exists('EasyWeChat\Factory'));，输出 false 就说明类根本没注册进 autoloader。解决只需确保 require __DIR__.'/vendor/autoload.php'; 在使用 SDK 前执行，且路径正确。
调用 $app->oauth->scopes(['snsapi_userinfo']) 却跳转到错误域名
OAuth 授权跳转地址由配置中的 redirect_uri 决定，但这个值**不是**在代码里传参控制的，而是在实例化时通过配置数组注入的。很多人误以为 scopes() 或 redirect() 方法能动态改回调地址，其实不能。
正确写法是：
$config = [
'app_id' => 'wx1234567890abcdef',
'secret' => 'your_app_secret',
'redirect' => 'https://yourdomain.com/callback', // ← 这里才是真正的回调地址
];
$app = EasyWeChatFactory::officialAccount($config);
$oauth = $app->oauth;
$url = $oauth->scopes(['snsapi_userinfo'])->redirect()->getTargetUrl(); // ← 不传参
若线上环境用了 Nginx 反向代理或负载均衡，还要检查 $_SERVER['HTTP_HOST'] 是否被污染——微信要求 redirect_uri 域名必须与公众号后台「授权回调域名」完全一致（不带 http://，只填 yourdomain.com），哪怕多一个 www 都会触发 redirect_uri domain error。
发送模板消息返回 invalid template_id
模板 ID 是在微信公众号后台「模板库」中选用后生成的，形如 TM000123456789，它和你在代码里写的 template_id 字符串必须**一字不差**，包括大小写和前缀。常踩的坑有：
- 复制时带了全角空格或换行（建议双击选中再复制）
- 用了测试号模板 ID 去调正式号接口（反之亦然）
- 模板未通过审核，状态还是「审核中」
- 调用的是订阅消息接口（
subscribe_message），却传了旧版模板消息 ID
调试时可先用 curl -X GET "https://api.weixin.qq.com/cgi-bin/template/get_all_private_template?access_token=xxx" 查看当前账号已添加的模板列表，确认 ID 是否存在、状态是否为 ok。
微信的配置项和接口行为高度依赖上下文，比如同一个 access_token 在 JS-SDK 和服务端 API 里可能因 scope 不同而失效；OAuth 获取的 openid 也不能直接拿去调用支付接口——这些边界条件，不跑一遍真实流程根本绕不开。
