telescope能逐层定位文件上传问题：检查表单enctype、中间件拦截及驱动配置，通过“files”验证是否接收文件，“logs”追踪storage执行，“events”核对磁盘路径映射，并结合ssh确认软链接与权限。
当你在Laravel项目中上传文件后发现存储路径不对、文件名被意外修改、或Storage::put()返回true但实际磁盘上没有文件，Telescope能帮你逐层定位是表单解析出错、中间件拦截、还是驱动配置失效。
启用Telescope并捕获上传请求
执行php artisan telescope:install → php artisan migrate → php artisan telescope:publish，确保APP_DEBUG=true且TELESCOPE_ENABLED=true。
访问http://your-app.test/telescope，确认右下角小图标显示“Telescope is active”。如果图标灰显，【检查.env中TELESCOPE_ENABLED=false是否被注释掉】。
在浏览器提交一个含的表单，务必使用POST方法并设置enctype="multipart/form-data"，否则Telescope将只记录空的request内容。
在Telescope中过滤并查看上传详情
进入Telescope首页 → 点击“Requests”标签 → 在搜索框输入“/upload”或你实际的路由URI → 找到刚提交的POST请求条目。
点击该条目进入详情页，左侧菜单选择“Request” → 向下滚动至“Files”区域，这里会列出所有上传的文件对象，包括临时路径、原始名称、MIME类型和大小。
若此处为空，说明Laravel根本未接收到文件——问题出在前端表单或Nginx/Apache配置（如client_max_body_size限制）；若存在但后续Storage操作失败，则继续往下查。
追踪Storage写入操作
在同一请求详情页，切换到“Queries”标签 → 查看是否有DB写入（如保存文件路径到数据库）；再切到“Jobs”标签 → 检查是否有队列任务触发存储逻辑。
最关键的步骤是点开“Logs”标签 → 滚动查找包含“store”、“put”、“write”的日志行，注意时间戳是否与上传动作吻合；若没找到，说明Storage::put()根本未被执行，需回溯控制器逻辑。
方法一：在控制器中上传逻辑前加Log::info('About to store file', ['path' => $path]); → 提交后在“Logs”里搜“About to store file”，确认代码是否运行到这里。
方法二：直接在Storage::put()调用后加dd(Storage::exists($path))，但这会中断流程，无法在Telescope中留痕；而Telescope的“Exceptions”标签能捕获StorageException，比如disk配置错误或目录无写权限时抛出的异常。
验证磁盘驱动与路径映射
第一步：打开config/filesystems.php → 找到你使用的disk（如's3'或'public'）→ 记录其'driver'和'root'值。
第二步：在Telescope的同一请求详情页 → 切换到“Events”标签 → 搜索“FilesystemManager”或“StoragePathResolved”事件 → 点击展开，查看实际解析出的绝对路径是否与config中root一致。
第三步：对比该路径与服务器真实目录结构。例如配置中root为storage_path('app/public')，但实际部署时public/storage软链接未运行php artisan storage:link，就会导致文件写入到物理路径却无法通过URL访问。
这一步不能只看Telescope日志，必须SSH登录服务器，用ls -l检查对应目录是否存在且权限为755、属主为web服务器用户（如www-data）。
