必须用 Composer 安装社区维护版 backblaze/b2-sdk-php，初始化需传 accountId 和 applicationKey；上传前须调 getUploadUrl 获取新鲜 URL 和 token，不可复用；下载私有 bucket 文件须用 downloadFileByName；大文件需手动分块流式上传并校验每块 SHA1。
Backblaze B2 SDK for PHP 怎么装和初始化
官方 SDK 不再维护，必须用社区维护的 b2-sdk-php（由 backblaze/b2-sdk-php 提供）。Composer 是唯一可靠方式，直接 require 会导致签名失败或 401。
- 运行
composer require backblaze/b2-sdk-php，别手动下载 ZIP 或改 autoload - 初始化时必须传入
accountId和applicationKey，不能只传 keyID —— 后者是旧 v1 API 的字段，v2 已弃用 - 如果用临时凭证（如通过 IAM 角色获取），
applicationKey必须是完整密钥字符串，不是“keyID + key”拼接
上传文件时怎么避免 400 Bad Request: uploadUrl required
这个错误说明你跳过了 getUploadUrl 或复用了过期的 uploadUrl。B2 要求每个上传请求都带新鲜的 URL 和授权 token，不能像 S3 那样长期复用 presigned URL。
- 每次上传前必须调用
$b2Client->getUploadUrl(['bucketId' => $bucketId])，哪怕只是上传一个文件 - 返回的
uploadUrl和authorizationToken有效期约 24 小时，但实际建议单次上传后丢弃，不缓存重用 - 上传 body 必须是原始二进制流，不能是 JSON 字符串；
Content-Type设为application/octet-stream，否则可能被拒绝 - 示例关键片段：
$upload = $b2Client->uploadFile([ 'uploadUrl' => $uploadInfo['uploadUrl'], 'authorizationToken' => $uploadInfo['authorizationToken'], 'fileName' => 'photos/2024/photo.jpg', 'content' => file_get_contents('/tmp/photo.jpg'), 'contentType' => 'image/jpeg' ]);
下载文件为什么返回空内容或 403
B2 下载分两类：公开 bucket 直接 GET，私有 bucket 必须用 downloadFileByName 并走认证流程。多数 403 是权限或路径没对上。
- 确认 bucket 是 public 还是 private —— 即使开了
readFiles权限，private bucket 仍需 SDK 认证下载 -
downloadFileByName的fileName是完整路径（如logs/app-2024-06.log），不是相对路径或带前导/ - 不要自己拼接下载 URL：B2 的
downloadUrl格式是https://f00X.backblazeb2.com/file/{bucketName}/{fileName}，但必须加?Authorization=...查询参数才能生效，SDK 自动处理，手拼极易出错 - 如果要用直链，先调
getDownloadAuthorization拿短期 token，再拼到 URL 后面，不能裸连
大文件分块上传怎么控制内存不爆掉
PHP 默认把整个文件读进内存，上传 100MB+ 文件大概率触发 Allowed memory size exhausted。B2 支持分块，但 SDK 不自动分，得自己切片并管理 SHA1。
立即学习“PHP免费学习笔记（深入）”；
- 用
fopen($path, 'rb')+fread()流式读取，每次读 5–10MB，计算每块的sha1_file()（注意：必须是块内容本身，不是整个文件） - 先调
startLargeFile拿fileId，再循环调uploadPart，最后finishLargeFile - 别忽略
partNumber必须从 1 开始连续，跳号或重复会导致400 Invalid part number - 上传完记得清理临时
largeFileId，否则会卡在 “uploading” 状态，影响后续同名文件覆盖
