laravel自定义磁盘需手动注册驱动类并绑定实例，仅修改config/filesystems.php无效；常见错误包括驱动未注册、扩展未启用、路径权限不匹配及fastdfs需nginx反代等。
Laravel 自定义磁盘不是改个 config/filesystems.php 就能用，必须确保驱动类已注册、实例已绑定、路径与权限自洽，否则 Storage::disk('xxx')->put() 会静默失败或抛出 Driver [xxx] not supported。
为什么改了 disks 数组还报错 Driver not supported
因为 Laravel 的磁盘注册是两阶段的：配置（config/filesystems.php）只负责声明“我想要一个叫 fastdfs 的磁盘”，但不负责“怎么造出这个磁盘”。驱动类没加载、没绑定到容器、没实例化，Laravel 就不认识它。
常见错误现象：
-
Driver [fastdfs] not supported—— 驱动类未注册，服务提供者没生效 -
Class 'Overtrue\Flysystem\FastDFS\Client' not found—— 没装overtrue/flysystem-fastdfs或 PHP sockets 扩展未启用 -
put()返回false且无异常 —— 客户端连接 tracker 失败（如 IP/端口错、防火墙拦截、tracker 未运行）
实操建议：
- 先确认扩展已安装：
composer require overtrue/flysystem-fastdfs - 检查
php -m | grep sockets，确保sockets扩展启用 - 不要在
config/filesystems.php里写'driver' => 'fastdfs'，Laravel 原生根本不认识这个词；留空或填'custom'即可，实际靠服务提供者接管 - 新建
app/Providers/FastDFSDiskServiceProvider.php，并在register()中绑定实例，不是boot()
config/filesystems.php 里 disks 怎么填才不白配
这里的配置不是“最终执行逻辑”，而是“给 Laravel 一个入口提示 + 供其他地方读取的元信息”。重点是字段语义别错位，尤其 root、url、visibility 这三个。
实操建议：
-
local磁盘必须设root，且值为storage_path('app')这类动态路径，不能硬写/var/www/storage/app -
public磁盘的visibility必须是'public'，url必须匹配你运行过php artisan storage:link后生成的软链路径（即APP_URL . '/storage'） -
s3/oss/fastdfs类磁盘禁用root字段，填了会触发 Flysystem 报错；凭据一律用env()加载，例如'access_key_id' => env('OSS_ACCESS_KEY_ID') - 磁盘名只用小写字母和下划线，比如
'oss_images'合法，'OSS-Images'或'oss images'会导致调用失败
FastDFS 磁盘必须手动注册服务提供者
这是最常被跳过的一步。Laravel 不会自动扫描第三方适配器，overtrue/flysystem-fastdfs 只提供适配器类，不自动注册磁盘驱动。
实操建议：
- 新建
app/Providers/FastDFSDiskServiceProvider.php，继承ServiceProvider - 在
register()方法中写绑定逻辑，示例：
$client = new \Overtrue\Flysystem\FastDFS\Client([
'tracker_hosts' => [['host' => '192.168.10.101', 'port' => 22122]],
]);
$adapter = new \Overtrue\Flysystem\FastDFS\Adapter($client);
$filesystem = new \League\Flysystem\Filesystem($adapter);
$this->app->singleton('filesystem.disk.fastdfs', function () use ($filesystem) {
return $filesystem;
});
然后在 config/app.php 的 providers 数组末尾加上 App\Providers\FastDFSDiskServiceProvider::class。
注意：singleton 绑定的是 filesystem.disk.{disk_name}，不是 filesystem 本身，名称必须和你在 config/filesystems.php 中声明的磁盘名一致（比如 'fastdfs'）。
OSS/S3/FTP 等云存储磁盘的 url 字段不能省
本地磁盘调用 url() 是拼路径，云存储磁盘必须显式返回可访问 URL，否则 Storage::disk('oss')->url('xxx.jpg') 会返回空字符串或错误前缀（如 https://bucket.oss-cn-hangzhou.aliyuncs.com/xxx.jpg 拼错）。
实操建议：
- OSS 磁盘必须配置
url，值为 Bucket 对应的外网访问域名，例如'url' => 'https://my-bucket.oss-cn-hangzhou.aliyuncs.com'，不能依赖 SDK 自动生成 - S3 磁盘若用自定义 endpoint（如 MinIO），
url也得显式配，且协议、端口、路径要和实际访问一致 - FTP/SFTP 磁盘无法生成公开 URL，
url()方法默认不可用；如需访问，得自己实现 URL 构造逻辑或改用代理路由
最容易被忽略的点：FastDFS 没有内置 HTTP 服务，Nginx 必须反向代理 tracker 或 storage 节点，并按 FastDFS 的 HTTP 规则解析 group 和 filename 路径，否则前端拿到 URL 也打不开图片。
