大屏、地图和外部资源问题记录

本文是「bylcloud-web 开发问题记录」系列之一。bylcloud-web 是基于 Vue 3 + Vite + Element Plus 的企业后台系统，笔记按「现象、排查、处理、下次注意」记录开发中真实遇到的问题。

记录 1：大屏页面最怕容器尺寸不稳定

控制中心和数据大屏这类页面和普通后台列表不一样。普通页面内容高度多一点少一点问题不大，但大屏对容器尺寸很敏感。图表初始化时如果容器宽高是 0，后面就可能显示空白或尺寸错乱。

我后面处理这类页面时，会优先确认：

• 父容器是否有明确高度。
• tab、弹窗、折叠面板切换后是否需要 resize。
• 页面首次渲染时接口数据是否已经回来。
• 图表实例销毁时有没有解绑监听。

这类问题经常不是数据错，而是初始化时机错。

记录 2：地图 key 和接口地址要分开查

项目里地图相关配置在 urlConfig.js，包括 mapKey、mapApi、trackKey。地图页面出问题时，我一开始会先看业务接口，后来发现地图类问题要分两层查：

1. 业务接口有没有返回项目、坐标、轨迹数据。
2. 地图 SDK 或地图服务本身有没有加载成功。

如果地图底图都没有出来，多半不是业务接口问题；如果底图正常但点位没有，多半才是业务数据或坐标转换问题。

这个排查顺序能省不少时间。

记录 3：文件预览地址需要 encode

项目里有 KKUrl 文件预览地址，通常是把文件 url 拼到预览服务后面。有些文件路径里带中文、空格或特殊字符时，如果没有 encode，预览服务可能打不开。

当时遇到的现象是：同一个预览功能，有的文件能打开，有的文件打不开。后来才发现不是文件类型问题，而是 URL 参数没有处理好。

以后处理类似地址拼接，要记住：

• 原始文件地址先确认可访问。
• 拼到预览服务前做 encode。
• 不要重复 encode。
• 如果文件来自 OSS，注意是否带临时签名参数。

记录 4：OSS bucket 切错会导致“上传成功但看不到文件”

测试和生产使用不同 OSS bucket。前端配置里有 ossBucket。有一次排查上传问题，接口返回成功，但页面预览拿不到文件。后来看配置，发现当前环境 bucket 和接口返回的访问域名不是一套。

这类问题很容易被误判成上传组件问题。实际排查顺序应该是：

1. 看前端当前环境的 bucket。
2. 看上传接口返回的 key 或 url。
3. 直接浏览器访问文件地址。
4. 再看组件回显逻辑。

上传组件只是最后一层，不能一出问题就先改组件。

记录 5：html2canvas 和 jspdf 生成文件时要先看样式

项目里有导出图片、导出 PDF 相关依赖。导出功能最常见的问题是：页面上看着正常，导出的内容错位、字体不对或图片没加载。

我后面处理这类问题会先做三件事：

• 等图片加载完成后再截图。
• 避免截图区域里有滚动容器。
• 导出前固定宽度，减少响应式布局影响。

导出问题通常不是一行代码能解决，更多是 DOM、样式和资源加载状态共同影响。