think-filesystem 1.x 升级到 2.x 必须强制重装并迁移配置：执行composer remove topthink/think-filesystem && composer require topthink/think-filesystem:^2.0，验证getadapter()方法存在；配置需拆分至config/filesystem.php（磁盘定义）和config/app.php（filesystem数组设default/url）；云驱动须换用支持flysystem v3的sdk，且需确保runtime/cache可写以避免静默失败。
think-filesystem 1.x 升级到 2.x 必须重装
TP6 默认用 topthink/think-filesystem v1.x，TP8 要求 v2.x —— 这不是简单 composer update 能解决的。v2.x 重构了驱动抽象层、移除了对 league/flysystem v1 的绑定，且接口签名变更（如 write() 返回值类型、listContents() 结果结构）。直接保留旧包会导致调用失败或静默返回 false。
执行以下命令强制替换：
composer remove topthink/think-filesystem composer require topthink/think-filesystem:^2.0
注意：^2.0 不要写成 ^2，后者可能拉到不兼容的预发布版；安装后检查 vendor/topthink/think-filesystem/src/Driver.php 是否存在 getAdapter() 方法（v2.x 新增），这是最简验证方式。
配置文件迁移：从 config/filesystem.php 到 config/filesystem.php + app.php
TP6 把全部文件系统配置收在 config/filesystem.php；TP8 拆成两部分：基础驱动定义仍在 config/filesystem.php，但默认磁盘、全局开关（如 default、url）必须挪到 config/app.php 的 'filesystem' 数组里，否则框架初始化时读不到默认磁盘。
-
config/filesystem.php保留'disks'数组，内容结构不变（如'local'、'qiniu'配置项） -
config/app.php中新增或修改'filesystem'键：
'filesystem' => [
'default' => 'local',
'url' => env('FILESYSTEM_URL', '/uploads'),
],
漏掉这步，Filesystem::disk()->put() 会报 InvalidArgumentException: Disk [local] does not exist，而不是提示配置缺失。
云存储驱动（OSS/Qiniu/COS）需同步升级 SDK 版本
TP8 的 think-filesystem v2.x 强制依赖 league/flysystem v3，而老版阿里云 OSS、七牛、腾讯云 COS 的 ThinkPHP 封装包（如 overtrue/flysystem-oss）多数只适配 v1 或 v2。直接启用会抛出 Class not found 或 Call to undefined method。
正确做法是换用官方维护或已明确支持 Flysystem v3 的包：
- 阿里云 OSS：
composer require aliyuncs/aliyun-oss-php-sdk:^2.7+composer require league/flysystem-aws-s3-v3:^3.0（OSS 兼容 S3 协议） - 七牛：
composer require qiniu/php-sdk:^7.10+composer require overtrue/flysystem-qiniu:^3.0 - 腾讯云 COS：
composer require qcloud/cos-sdk-v5:^2.6+composer require league/flysystem-cached-adapter:^3.0（注意：COS 官方 v5 SDK 已原生支持 Flysystem v3）
别复用 TP6 时代的 overtrue/flysystem-oss:1.x，它内部仍调用 Flysystem\AdapterInterface，而 v3 已改用 League\Flysystem\FilesystemOperator。
runtime 目录权限与缓存驱动冲突
TP8 默认启用 cached-adapter 包裹本地磁盘（见 config/filesystem.php 中 'local' 的 'cache' 配置），若服务器上 runtime/cache/ 不可写，或 PHP 进程用户无权创建子目录，Filesystem::disk('local')->put() 会静默失败（返回 false），且日志里不报错 —— 因为缓存层捕获了异常但没透出。
临时排查方法：
- 关掉缓存：把
'local'配置里的'cache'数组整个删掉，再试写入 - 检查权限：
ls -ld runtime/cache确认属主和写权限；若用宝塔，确认 PHP 运行用户（如www）对该目录有rwx - 确认
opcache.enable未禁用（TP8 文件系统部分逻辑依赖 OPcache 缓存类定义）
这个点最容易被忽略：问题现象是“文件存不进去”，但根源既不是代码也不是配置，而是 runtime/cache 目录卡住了底层适配器初始化。
