本地存储 文件系统 ClassLeagueFlySystemAdapterLocalNotFound 错误解决方法

本文目录导读：

1. 🔍 错误原因大揭秘
2. 🛠️ 手把手解决方案
3. 💡 进阶技巧
4. 🎉 验证成功

🚨 文件上传失败！本地存储适配器消失之谜
某天，你正在部署新项目，突然发现文件上传功能报错：Class 'League\Flysystem\Adapter\Local' not found，别慌！这个看似吓人的错误，其实可能只是“适配器迷路”了，本文带你一步步排查，让本地存储重回正轨！

🔍 错误原因大揭秘

1. Flysystem 版本不兼容
   📌 你可能安装了 Flysystem 3.x，但代码仍调用旧版命名空间（如 League\Flysystem\Local），新版 Flysystem 3.x 调整了命名空间，导致类找不到。

2. 路径配置翻车
   📂 本地存储路径未正确设置，或 PHP 进程无权限读写目标目录，适配器直接“罢工”。

3. 缓存适配器冲突
   🗃️ 在 Laravel 9+ 中，Flysystem 3.x 移除了旧版缓存适配器，若项目依赖旧包（如 league/flysystem-cached-adapter），可能引发版本冲突。

🛠️ 手把手解决方案

安装/更新 Flysystem 库

🔧 Composer 命令：

   composer require league/flysystem:^3.0

⚠️ 若项目使用 Laravel 6-8，需锁定 Flysystem 1.x：

   composer require league/flysystem:"^1.0.34" --with-all-dependencies

检查命名空间

📝 修正代码引用：

   // 旧版（Flysystem 1.x）
   use League\Flysystem\Local\LocalFilesystemAdapter;
   // 新版（Flysystem 3.x）
   use League\Flysystem\Adapter\Local;

配置本地存储路径

📂 初始化适配器：

   use League\Flysystem\Filesystem;
   use League\Flysystem\Adapter\Local;
   $adapter = new Local(__DIR__ . '/storage/app');
   $filesystem = new Filesystem($adapter);

🔑 权限设置：

   chmod -R 755 storage/app
   chown -R www-data:www-data storage/app  # 根据Web服务器用户调整

清理 Composer 缓存

🧹 重建自动加载：

   composer dump-autoload

处理缓存适配器冲突（Laravel 用户）

🗑️ 移除旧包：

   composer remove league/flysystem-cached-adapter

🔄 升级 Laravel 配置：

   // config/filesystems.php
   'local' => [
       'driver' => 'local',
       'root' => storage_path('app'),
   ],

💡 进阶技巧

• 内存不足？ 调整 php.ini：

  memory_limit = -1

• 启用扩展：确保 fileinfo 和 zip 扩展已加载（PHP 8.0+ 必需）。
• 调试路径：使用 var_dump($adapter->getRoot()) 验证路径是否正确。

🎉 验证成功

完成以上步骤后,运行以下代码测试：

$filesystem->write('test.txt', 'Hello, Flysystem!');
echo $filesystem->read('test.txt'); // 输出 "Hello, Flysystem!"

🔥 ：这个错误本质是“适配器找不到”，通过升级库、修正命名空间、配置路径三步即可解决，遇到版本冲突时，记得用 composer why 排查依赖链！

📅 信息来源：本文基于 2025 年 8 月最新 Flysystem 3.x 文档及开发者社区案例整理，适配 PHP 8.0+ 环境。