ThinkPHP 6/7 接入腾讯云 COS 直传必须由服务端生成签名并校验回调，因前端无法安全持有 SecretKey 且时间同步不可靠；需用 qcloud/cos-sdk-v5 生成含合法 callbackUrl 和 callbackBody 的预签名参数，确保 COS 控制台回调配置与后端接口协议、域名、路径完全一致，并正确处理 X-Cos-Security-Token 与 FormData 字段名。
ThinkPHP 6/7 接入腾讯云 COS 直传，核心不是“能不能传”，而是签名必须由服务端生成、且回调地址必须校验签名——否则前端直传会 403 Forbidden 或回调被 COS 拒绝。
为什么不能在前端直接拼接 COS 签名？
腾讯云 COS 的直传签名（q-signature）依赖临时密钥（q-key-time、q-sign-time）、请求路径、HTTP 方法、头部和参数的完整哈希，且有效期严格限制（通常 ≤ 15 分钟）。前端无法安全持有 SecretKey，也无法可靠同步服务器时间，硬编码或 JS 生成必然失败。
- 前端用
SecretKey算签名 = 泄露密钥，等于开放整个 COS 存储桶 - 客户端时间不准会导致
q-sign-time范围校验失败，COS 直接拒收 - COS 回调（
callbackUrl）必须带有效签名，否则回调请求被 COS 当作伪造丢弃
ThinkPHP 6/7 生成直传签名的最小可行代码
使用官方 SDK qcloud/cos-sdk-v5（v2.6+ 支持直传签名），不建议手写签名逻辑。关键点：签名必须包含回调所需全部字段，且 callbackBody 格式要与你后端回调接口预期完全一致。
// app/Service/CosService.php
use Qcloud\Cos\Auth\QCloudAuthClient;
<p>public function getPresignedPostParams(string $key, array $callbackData = []): array
{
$cosConfig = config('cos');
$authClient = new QCloudAuthClient(
$cosConfig['secret_id'],
$cosConfig['secret_key'],
$cosConfig['region']
);</p><pre class="brush:php;toolbar:false;">$bucket = $cosConfig['bucket'];
$path = '/' . ltrim($key, '/');
// 回调配置（必须与 COS 控制台「跨域设置→回调 URL」一致）
$callbackUrl = url('api.cos.callback'); // 例如 /api/cos/callback
$callbackBody = json_encode([
'key' => $path,
'mimeType' => '$(mimeType)',
'size' => '$(fileSize)',
'hash' => '$(sha1)',
'filename' => '$(fileName)',
], JSON_UNESCAPED_UNICODE);
return $authClient->getPresignetPostParams([
'Bucket' => $bucket,
'Key' => $path,
'Fields' => [
'callbackUrl' => $callbackUrl,
'callbackHost' => parse_url($callbackUrl, PHP_URL_HOST),
'callbackBody' => $callbackBody,
'callbackBodyType' => 'application/json',
],
'Conditions' => [
['content-length-range', 0, 20 * 1024 * 1024], // 20MB 限制
],
'Expires' => 900, // 秒，必须 ≤ 900（15 分钟）
]);}
-
callbackHost必须填域名（不能是 IP 或 localhost），否则 COS 回调时会报Invalid callback host -
callbackBody中的$(xxx)是 COS 预置变量，大小写敏感，$(fileName)≠$(filename) - 返回的
policy和signature必须原样透传给前端，不能 URL decode 或 JSON encode 二次处理
COS 控制台回调配置与 ThinkPHP 接口对齐要点
COS 控制台设置的「回调 URL」和后端 api.cos.callback 接口必须满足三同：协议同、域名同、路径同。否则 COS 发起回调时会因 Host 不匹配而失败，日志里只显示 callback failed，无具体错误。
腾讯云通用文字识别（高精度版）技能包。用户发送/粘贴图片、提供图片URL或要求识别图片文字时自动调用。支持中文、英文、中英混合、数字及特殊符号的检测与识别，返回文字框位置与内容。适用于文字较多、版式复杂、准召率要求高的场景。
- 控制台填写的回调地址必须是公网可访问地址（如
https://api.example.com/api/cos/callback），不能是http://localhost - ThinkPHP 接口需关闭 CSRF 验证（COS 回调不带 token），加
#[Middleware(DisableCsrfToken::class)]或在中间件中排除 - 接口必须验证
Authorization头中的回调签名，SDK 提供Qcloud\Cos\Signature\CallbackSignature类校验，不校验 = 接口可被任意伪造调用 - 收到回调后，应解析
body中的 JSON，提取key和etag，存入数据库并返回200 OK；返回非 2xx 会导致 COS 重试（最多 3 次）
前端上传时容易漏掉的两个 header
很多开发者只传 key、policy、signature，却忽略 COS 强制要求的两个 header，导致 400 Bad Request：
-
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary...（浏览器自动加，不用手动设） -
X-Cos-Security-Token：如果用了临时密钥（STS），这个字段必须存在且值为credentials.sessionToken；若用长期密钥则**不能传该 header**，否则 COS 拒绝 - 上传
<input type="file">时，FormData的 key 必须叫file（COS 默认字段名），不能改成upload或其他，否则400
最简上传片段：
const formData = new FormData();
formData.append('key', 'uploads/test.jpg');
formData.append('policy', response.policy);
formData.append('signature', response.signature);
formData.append('file', fileInput.files[0]);
<p>fetch('<a href="https://www.php.cn/link/4b6424d40c97d82d476d0b30522253c0">https://www.php.cn/link/4b6424d40c97d82d476d0b30522253c0</a>', {
method: 'POST',
body: formData,
});</p>
真正卡住人的往往不是签名算法，而是回调地址协议/域名不一致、X-Cos-Security-Token 误传、或 callbackBody 字段名拼错——这三个地方查日志几乎看不到明确提示，得靠抓包比对 COS 文档字段定义。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
