ThinkPHP文件存储核心是磁盘配置与业务路径解耦，$key须为不含根目录的纯相对路径；正确生成需兼顾多应用隔离、日期分层、中文名安全、云存储兼容及统一URL访问逻辑。
ThinkPHP 文件存储不是“配个路径就能用”，核心在于磁盘（disk）配置与业务路径生成逻辑的解耦——Storage::disk('upload')->put($key, $file) 中的 $key 必须是纯路径字符串，不带根目录；而 $key 的生成方式，决定了你能否应对多应用、日期分层、中文文件名、云存储切换等真实问题。
为什么 Storage::put() 写不到 public/storage 下？
常见错误是直接传入 'public/storage/avatar/1.jpg' 这类含盘根的路径，或手动拼 public_path('uploads')。ThinkPHP 的 put() 方法只接受相对路径（即 key），它会自动拼到当前 disk 的 root 后面。
- 正确做法：确保
config/filesystem.php中'upload'磁盘的root已设为public_path('uploads')，然后调用Storage::disk('upload')->put('avatars/2024-06/15/abc.jpg', $file) - 错误写法：
Storage::disk('upload')->put(public_path('uploads/avatars/1.jpg'), $file)—— 这会尝试往public_path('uploads') . '/public_path(...)/...'写，路径爆炸 - 多应用下注意：
public_path()返回的是全局 public 目录，若需按应用隔离，应改用app()->getAppPath() . '../public/uploads/' . app('http')->getName() . '/'
日期+哈希分层目录怎么安全生成？
避免单目录文件过多导致系统卡顿，必须在 $key 里加入时间戳和哈希，但不能简单用 date('Y/m/d') —— 斜杠在 Windows 下会被误解析为目录分隔符，且 Flysystem 对路径中开头的 / 敏感。
- 推荐结构：
date('Y-m') . '/' . date('d') . '/' . md5($file->getOriginalName() . time()) . '.' . $file->extension() - 关键点：
date('Y-m')和date('d')分开拼，不用斜杠；哈希后缀防止重名，且不依赖原始文件名中的中文或空格 - 别在控制器里手动
mkdir——Storage::put()会自动创建中间目录，前提是 disk 的root所在父目录 PHP 有写权限 - 测试时可先用
Storage::disk('upload')->exists('2024-06')验证路径是否可达
上传中文名文件后访问 404 怎么办？
浏览器下载时乱码、Nginx 报 open() "/path//E6%8A%A5" failed (2: No such file)，本质是 URL 编码与文件系统路径不一致。ThinkPHP 不处理文件名编码转换，得靠业务层规整。
立即学习“PHP免费学习笔记（深入）”；
- 绝对不要用
$file->getClientOriginalName()直接作 key —— 它带中文、空格、括号，本地可能侥幸成功，OSS/Qiniu 会拒绝或返回异常 key - 安全方案：用
md5(uniqid() . $file->getClientOriginalName()) . '.' . $file->extension()，或更可控地提取拼音首字母 + 时间戳（需引入中文转拼音库） - 访问链接必须走
Storage::url($key)，而不是自己拼/storage/xxx—— OSS 返回 CDN 地址，local 才返回相对路径，硬拼会跨驱动失效 - 如果必须保留原始语义（如 SEO 友好），可在数据库存原始名，
$key仍用哈希，访问时通过路由代理（如/download/{id}）读取并设置Content-Disposition头
切到七牛/OSS 后路径逻辑全乱了？
根本原因是把本地路径思维带进了云存储：OSS 没有“目录”概念，只有 key 前缀；Qiniu 的 domain 必须备案且协议匹配；所有驱动共用同一套 $key 生成逻辑，但 url() 行为不同。
- filesystem.php 中云磁盘的
root应留空或设为''，别填https://xxx—— 它只用于 local 驱动，填了反而干扰 - 七牛配置里
bucket必须全小写、不含区域后缀（如z2），区域单独写region；domain必须是已绑定该 bucket 的 CDN 域名，且useHttps要和 domain 协议一致 - 上传后调试：打印
Storage::disk('qiniu')->url('2024-06/15/abc.jpg')，看是否返回完整 HTTPS 地址；若返回/2024-06/...，说明 disk 没生效，正在 fallback 到 default - 最易忽略的坑：.env 里变量没加引号导致空格截断，比如
OSS_ACCESS_KEY=xxx yyy实际只读到xxx，报 Invalid signature
真正难的不是写几行配置，而是让 $key 在本地开发、测试环境、生产 OSS、灰度七牛之间保持语义一致且可追溯——它得能反查来源、支持批量清理、不因驱动切换而断裂。路径生成逻辑一旦写死在控制器里，后面换存储就是一场重构。把它抽成独立服务类，加单元测试覆盖中文、空格、超长名场景，比调通第一个上传更重要。
