必须使用 tencentcloud-sdk-php:^3.0 替代已停更的 QcloudApi，初始化用 TencentCloud\Iai\V20200303\IaiClient；VerifyFaceId 要求 base64 图片无 data: 前缀、仅 jpg/jpeg/png、≤1MB、480×640 以上；身份证号和姓名须 UTF-8 + URL 编码；回调需 HTTPS、200 空响应、读取 php://input 并验签。
腾讯云人脸核身 PHP SDK 初始化失败
直接用 QcloudApi 或手动拼 URL 调用，90% 的人卡在第一步：SDK 初始化报错 Class 'QcloudApi\QcloudApi' not found。这不是你代码写错了，是腾讯云官方 PHP SDK 已停止维护，且不兼容 PHP 7.4+（尤其 Composer 自动加载机制变化后）。
- 别再搜「腾讯云 PHP SDK 下载」——官网已下架，GitHub 上的旧版
qcloudapi-sdk-php无法通过composer require正常安装 - 实际可用路径只有一条：用腾讯云新版
TencentCloudSDK（即tencentcloud-sdk-php），它基于 OpenAPI 3.0，支持 PHP 7.2–8.2 - 安装命令必须带版本约束：
composer require tencentcloud-sdk-php:^3.0（不加^3.0可能装到不兼容的 v4 beta 版） - 初始化时注意命名空间：
use TencentCloud\Iai\V20200303\IaiClient;，不是QcloudApi，也不是TencentCloud\Iai\IaiClient
调用 VerifyFaceId 接口返回 InvalidParameter.ImageDataInvalid
这个错误不是图没传，而是图的编码/格式/尺寸踩了腾讯云硬性规则。人脸核身要求的是「原始证件照级质量」，不是随便截个屏或拍张模糊身份证就能过。
- 图片必须是 base64 编码后的字符串，且不能带
data:image/jpeg;base64,前缀——很多人直接用前端canvas.toDataURL()结果就挂在这儿 - 支持格式仅限
jpg、jpeg、png；GIF、WebP、BMP 全部拒收 - 文件大小严格限制在 1MB 以内，超一点就报这个错；建议服务端收到 base64 后先解码并检查
strlen($decoded) - 分辨率不能低于 480×640，但也不能太高（如 4K 图），否则 base64 字符串过长触发接口长度限制
PHP 中如何安全传递身份证号和姓名给腾讯云
别把 $idCard 和 $name 直接塞进请求体发过去——腾讯云 VerifyFaceId 接口要求这俩字段必须做 UTF-8 编码 + URL 编码，且顺序、大小写、空格全敏感。
- 姓名必须用
urlencode(mb_convert_encoding($name, 'UTF-8', 'auto'))，不能只用urlencode($name)（中文乱码会直接返回InvalidParameter.NameFormatError） - 身份证号不能有任何空格、短横线、字母（哪怕用户输的是
11010119900307251X，也得确保最后的X是大写） - 请求参数必须按文档顺序组织：
IdCard、Name、ImageBase64，字段名大小写一个都不能错（idcard或IDCARD都会 400） - 强烈建议封装校验函数：
isValidIdCard($id)检查 18 位+末位校验码，isValidName($name)过滤 emoji 和控制字符
回调地址接收不到腾讯云的核验结果
腾讯云人脸核身不走实时同步返回，而是异步回调（CallbackUrl）。很多人设了地址却收不到，问题基本出在 HTTP 协议、响应头或 Body 解析上。
立即学习“PHP免费学习笔记（深入）”；
- 回调地址必须是公网可访问的 HTTPS 地址（HTTP 会被拒绝），且证书有效（Let’s Encrypt 可用，自签名证书不行）
- 你的 PHP 接口必须在 3 秒内返回 HTTP 200，且响应体为空（
echo '';即可），多一个空格、换行、BOM 头都会导致腾讯云重试或丢弃 - 回调 Body 是 raw JSON，不是
$_POST，得用$raw = file_get_contents('php://input');读取，再json_decode($raw, true) - 务必验证
Signature签名字段——腾讯云用 SHA256-HMAC + SecretKey 对整个 raw body 签名，漏验签等于裸奔
