直接用 composer require "overtrue/wechat:~5.0" 可安装 EasyWeChat 5.x，但常见问题源于 PHP 版本（需 ≥7.2）、Composer 源配置错误、版本混淆（4.x 与 5.x 命名空间及配置结构不同）、autoload 未正确引入，以及配置项如 aes_key 必须为字符串而非 null。
直接用 composer require "overtrue/wechat:~5.0" 就能装上 EasyWeChat 5.x（当前主流稳定版），但多数人卡在 autoload 失败、类找不到、或 Laravel 环境下服务提供者注册不生效——问题不在安装命令本身，而在依赖路径、PHP 版本约束和自动加载机制没对齐。
确认 PHP 版本与 Composer 仓库源
EasyWeChat 5.x 要求 PHP >= 7.2，且必须使用 Packagist 官方源或已同步的国内镜像（如阿里云、腾讯云）。若本地 Composer 配置了过期的私有源或禁用了 HTTPS，composer require 可能静默失败或拉到旧版 4.x。
- 运行
php -v确保输出为PHP 7.2.5或更高 - 执行
composer config -g repo.packagist composer https://packagist.org强制回官方源（临时排障可用） - 国内用户建议用
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
安装命令与版本号必须匹配实际需求
EasyWeChat 主要有两个大版本共存：4.x（Laravel 5.5–6.x 兼容）和 5.x（Laravel 7+ / 纯 PHP 项目推荐）。不指定版本可能因 Composer 自动降级导致引入 4.x，而 4.x 的命名空间是 Overtrue\WeChat，5.x 是 EasyWeChat\Kernel\MpService，混用会报 Class not found。
- 新项目统一用：
composer require "overtrue/wechat:~5.0"（注意引号，避免 shell 解析特殊字符） - 若需适配 Laravel 6.x 且不想升级框架，才考虑
composer require "overtrue/wechat:~4.4" - 执行后检查
vendor/overtrue/wechat/src/下是否存在Kernel目录 —— 有则为 5.x，无则大概率是 4.x
自动加载失效？检查 vendor/autoload.php 是否被正确引入
EasyWeChat 本身不注册全局 autoloader，它依赖 Composer 生成的 vendor/autoload.php。常见错误是手动 require 错误路径，或在 CLI 脚本中忘了加载。
- Web 环境下确保入口文件（如
index.php）第一行是：require __DIR__ . '/vendor/autoload.php';
- Laravel 用户无需手动加载，但要确认
config/app.php中是否遗漏了Overtrue\LaravelWeChat\ServiceProvider::class（仅限 4.x 包）；5.x 不提供 Laravel 服务提供者，应直接 new 实例 - CLI 脚本调试时，不能只写
require 'autoload.php'，必须用绝对路径或require_once dirname(__DIR__) . '/vendor/autoload.php';
实例化时报错 “Missing required parameters” 或 “Invalid config”
这不是安装问题，而是配置数组结构不匹配 SDK 版本。5.x 的配置键名全部小写且去掉了前缀，比如 app_id（不是 appid 或 APPID），secret（不是 app_secret），且必须包含 token 和 aes_key（即使不用消息加解密，也得设为空字符串）。
- 最小可用配置示例（5.x）：
$config = [ 'app_id' => 'wx1234567890abcdef', 'secret' => 'your_app_secret', 'token' => 'your_token', 'aes_key' => '', // 如不用加密，留空字符串，不能为 null ]; - 调用方式必须用
EasyWeChat\Kernel\MpService：$app = new \EasyWeChat\Kernel\MpService($config);
- 如果仍报错，用
var_dump(array_keys($config));确认键名全是小写、无空格、无 BOM
真正容易被忽略的是配置项的「空值处理」：5.x 把 aes_key 设为 null 会触发严格判断失败，必须是字符串；另外 composer dump-autoload -o 在修改 vendor 后没运行，也会导致新类无法识别——这些都不是安装步骤的问题，但会让人以为“装失败了”。
