正确安装命令是 composer require php-telegram-bot/core ^4.0，需先卸载旧版 irazasyed/telegram-bot-sdk；v4 版本不自动处理 Webhook，须确保 HTTPS、200 响应及 1 秒内返回，并显式注册命令与解析 Update。
composer require 时提示 package not found 或版本冲突
PHP-Telegram-Bot 官方库已停止维护，当前主流替代是 php-telegram-bot/core（原 irazasyed/telegram-bot-sdk 已弃用）。直接运行 composer require irazasyed/telegram-bot-sdk 会失败或拉取过时版本。
- 正确命令是：
composer require php-telegram-bot/core ^4.0（推荐 v4.x，兼容 PHP 8.0+） - 若项目已含旧版
telegram-bot-sdk，先执行composer remove irazasyed/telegram-bot-sdk再安装新包 - v4 默认不带 Webhook 服务器逻辑，需自行处理请求入口（如
webhook.php），这点和旧版自动注册路由不同
Webhook 配置后 Telegram 不推送消息到你的 endpoint
不是代码问题，大概率是网络或配置链路断在中间：Telegram 无法访问你的 URL，或你没正确响应 200 状态码。
- 确保 webhook URL 是 HTTPS（自签名证书不行，必须由可信 CA 签发）
- 用
curl -I https://your-domain.com/webhook.php检查是否返回HTTP/2 200，且无重定向、超时或 5xx - Telegram 要求 webhook endpoint 必须能处理 POST 请求，并在 1 秒内返回 HTTP 200 —— 如果你用了
sleep()或阻塞式数据库写入，会触发重试甚至关闭 webhook - 设置前先用
curl -X POST https://api.telegram.org/bot<token>/setWebhook -d "url=https://your-domain.com/webhook.php"</token>手动验证
收到消息但 handleUpdate() 不触发命令或回调
php-telegram-bot/core 的事件分发依赖严格的消息结构解析，常见于未启用相应更新类型或未注册命令处理器。
- 初始化 Bot API 时必须显式指定要接收的更新类型：
$bot->addCommand('start', \App\Commands\StartCommand::class)，否则/start不会被识别 - Webhook 接口里不能只写
$bot->handle();，得先调用$update = \TelegramBot\Api\Types\Update::fromArray($_POST);，再传给$bot->handle($update) - 如果用户发的是 inline query 或 callback_query，需单独调用
$bot->handleInlineQuery()或$bot->handleCallbackQuery()，默认不处理 - 命令类必须继承
\PhpTelegramBot\Core\Commands\BaseCommand，且execute()方法里不能抛出未捕获异常，否则整个 handle 流程中断
本地调试时如何绕过 Webhook 直接模拟消息
开发阶段频繁切 HTTPS + 部署太重，用 getUpdates 轮询模式更可控，且支持 file_get_contents('php://input') 模拟 POST 数据。
立即学习“PHP免费学习笔记（深入）”；
- 临时禁用 webhook：
curl -X POST https://api.telegram.org/bot<token>/deleteWebhook</token> - 写个
polling.php，循环调用$bot->getUpdates()（注意加sleep(1)避免限流） - 调试命令时，可手动构造 JSON 模拟 POST body：
file_put_contents('test-update.json', json_encode(['message' => ['text' => '/start', 'from' => ['id' => 123]]]));，再用json_decode(file_get_contents('test-update.json'), true)喂给handle() - 别在生产环境用 polling —— Telegram 对
getUpdates有严格频率限制（429 Too Many Requests错误很常见）
error_log("Webhook hit at " . date('c'));，确认请求到底有没有到达你的服务器。 
