spatie/dropbox-api 是当前最稳的选择：基于 Dropbox API v2、持续更新、无依赖冲突、不绑定框架、方法名直译 API 路径，但需手动管理 access_token 并注意路径编码与错误处理。
直接用 composer require spatie/dropbox-api 就能装好最轻量、维护活跃的 Dropbox PHP 客户端，不用碰 OAuth 流程也能快速调用 API。
选哪个库？spatie/dropbox-api 是当前最稳的选择
Dropbox 官方 PHP SDK 已归档，kunalvarma05/dropbox-php-sdk 停更多年，dropbox/dropbox-sdk（v1.4）仅支持旧版 API v1，早已不可用。而 spatie/dropbox-api 基于 Dropbox API v2，持续更新，无 Composer 依赖冲突，且只做一件事：发 HTTP 请求。
- 它不绑定框架，Laravel、Symfony 或纯 PHP 项目都能用
- 不封装 OAuth 流程——你得自己管理
access_token，但换来的是可控性和调试透明度 - 所有方法名直译 API 路径，比如
listFolder()对应files/list_folder，查文档时零认知成本
安装后必须手动配置 access_token
spatie/dropbox-api 不提供登录页或 token 获取逻辑，token 必须提前在 Dropbox App Console 创建应用并生成。别跳过这步，否则所有请求都会返回 401 Unauthorized。
- 创建应用时选择 “Scoped access”（推荐），勾选必要权限如
files.content.read、files.content.write - 生成 token 后，**不要硬编码在 PHP 文件里**，改用环境变量：
$_ENV['DROPBOX_ACCESS_TOKEN']或getenv('DROPBOX_ACCESS_TOKEN') - 初始化客户端时传入 token：
$client = new \Spatie\Dropbox\Dropbox($accessToken);
上传文件时注意路径和编码
Dropbox API v2 对路径要求严格：开头不能有 /，中文或空格需 UTF-8 编码，否则返回 path/not_found 或 bad_path 错误。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
立即学习“PHP免费学习笔记（深入）”；
- 正确写法：
$client->upload('/notes/report.pdf', $fileContents)（路径以/开头是合法的，但注意不是//notes/...） - 本地文件读取建议用
file_get_contents()，别用fopen+stream_get_contents，后者容易漏掉末尾换行或二进制截断 - 大文件（>150MB）需用
uploadSessionStart+uploadSessionAppend+uploadSessionFinish分块上传，库已封装，但得自己拆分 chunk
Laravel 项目优先用 flysystem-dropbox 适配器
如果你在 Laravel 里只是存取用户上传文件，别手写 Dropbox 调用——用 spatie/flysystem-dropbox 更省事，它把 Dropbox 当成一个「磁盘」，和本地存储用同一套 API。
- 装包：
composer require spatie/flysystem-dropbox - 在
config/filesystems.php中加磁盘配置：'dropbox' => [ 'driver' => 'dropbox', 'authorization_token' => env('DROPBOX_ACCESS_TOKEN'), ], - 之后就能用
Storage::disk('dropbox')->put('image.jpg', $content)，完全不用关心 API 细节
真正麻烦的不是装库，而是 token 生命周期管理和错误响应解析——429 Too Many Requests 没重试机制会崩，507 Insufficient Space 不检查就覆盖失败。这些不在 composer install 范围内，得你自己补。
