必须切换国内镜像源才能顺利安装，因Packagist官方源在国内访问极不稳定；推荐执行composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/全局启用腾讯云镜像，再运行composer require "overtrue/wechat:^6.0"完成安装。
国内直接 composer require overtrue/wechat 极大概率卡住或超时，根本原因是 Packagist 官方源在大陆访问不稳定。换国内镜像后，安装速度从“等半小时”变成“秒级完成”，这是刚需，不是优化。
确认 Composer 已安装且可用
别跳过这步——很多报错其实卡在这儿。执行 composer --version，如果提示“command not found”，说明 Composer 没装好或没加进系统 PATH。Windows 用户建议用官方安装器（.exe），Linux/macOS 推荐用 curl -sS https://getcomposer.org/installer | php + mv composer.phar /usr/local/bin/composer。
常见错误现象：Could not open input file: composer.phar 或 composer: command not found。这类问题不解决，换镜像也没用。
切换到腾讯或阿里云 Packagist 镜像
官方推荐的中国镜像已从 phpcomposer.com 迁移，当前稳定可用的是腾讯云镜像（https://mirrors.cloud.tencent.com/composer/）和阿里云镜像（https://mirrors.aliyun.com/composer/）。优先选腾讯云，实测响应更稳。
执行以下命令（全局生效）：
composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/
验证是否生效：composer config -g repo.packagist 应返回上述 URL；如果仍显示 packagist.org，说明配置失败，重试或加 -vvv 看详细错误。
- 不要用过期的 phpcomposer.com 镜像，它已于 2025 年底下线
- 项目级镜像配置（只对当前目录生效）用
composer config repo.packagist composer ...，去掉-g - 换镜像后首次运行
composer install可能触发缓存重建，稍慢属正常
安装 EasyWeChat 并验证基础可用性
进入你的项目根目录（不是 public，是含 composer.json 的那一层），执行：
composer require "overtrue/wechat:^6.0"
注意：EasyWeChat v6 是当前主力版本（2026 年主流 Laravel/TP6 项目适配的版本），别用已停止维护的 v4 或 v5。如果项目强制要求 PHP 7.4，才考虑 ^5.1，但需自行处理 JWT 依赖冲突。
安装成功后，快速验证 SDK 是否能加载：
<?php
require_once 'vendor/autoload.php';
use EasyWeChat\Factory;
$config = ['app_id' => 'xxx', 'secret' => 'xxx']; // 占位即可，不需真实值
try {
$app = Factory::officialAccount($config);
echo "SDK 加载成功";
} catch (\Exception $e) {
echo "加载失败：" . $e->getMessage();
}
如果输出 “SDK 加载成功”，说明 autoloader 和核心类路径都没问题；若报 Class 'EasyWeChat\Factory' not found，大概率是 vendor/autoload.php 路径不对，或 Composer 安装中途被中断（删掉 vendor 和 composer.lock 重装）。
真正容易被忽略的点：镜像只加速下载，不解决配置错误。AppID、Secret 写错，或者微信后台未开启服务器配置，照样收不到消息——镜像再快，也救不了逻辑 bug。
