按「设计/适配 / 数据 / 渲染 / 动画 / 稳定性 / 部署 / 协作」八类整理，每条都是真在项目里翻过车的。
一、设计与适配类
1. 设计稿尺寸和真实大屏对不上
- 现象：设计稿按 1920×1080 出，物理屏是 3840×1080 拼接，元素全跑偏。
- 根因：没在立项时和硬件方对齐基准分辨率。
- 避坑：立项第一周就把「前端输出分辨率 = 拼接屏控制器输入分辨率」写进文档，签字确认。
2. transform: scale 后 position: fixed 失效
- 现象：右下角悬浮告警栏
position: fixed，整屏 scale 后位置乱掉。 - 避坑：大屏内禁用 fixed，统一在 1920×1080 设计坐标系里 absolute；告警条用 absolute 定位到 stage 内。
3. 100vh / 100vw 在 Electron / 嵌入式 WebView 表现不一
- 现象：开发环境正常，部署到客户机房一打开顶部多一条白边。
- 根因：100vh 在某些 WebView 包含/不包含地址栏时计算不同。
- 避坑：大屏 stage 用固定
width/height+ scale，不依赖 vw/vh。
4. 高 DPR 屏 GPU 直接拉爆
- 现象：4K 屏 dpr=2，Three.js 把 buffer 渲染到 7680×2160，60fps 掉到 15fps。
- 避坑：
renderer.setPixelRatio(1)；2D Canvas 视情况保留 dpr。
5. iframe 嵌入第三方页面不缩放
- 现象：scale 整屏，唯独 iframe 里的页面不变。
- 避坑：iframe 外层包一个再 scale；或让对方提供 SDK / postMessage 协议自行渲染。
6. 字体在 LED 屏远距离糊
- 现象：开发本机看字号合适，到现场远 8 米看一片糊。
- 避坑：核心数字 ≥ 64px；字重 Medium 起步；标题用更粗的 Bold；现场实测一次。
7. 颜色在 LED 屏偏色
- 现象：#3FA8FF 在 LED 屏偏紫，#FFC53F 偏绿。
- 避坑：到现场用色卡校准；提供 2~3 套配色让客户挑；避免大面积浅灰渐变（LED 灰阶差）。
8. 设计稿里大量浅色阴影、玻璃拟物
- 现象：浏览器还行，LED 屏阴影看不见，玻璃模糊全没了。
- 避坑：大屏视觉用「高对比 + 发光描边」，阴影/blur/磨砂少用。
二、数据与实时推送类
9. 每个 widget 各起一个 WebSocket
- 现象：30 个图表，30 条 WS 连接，连接数告警 + 推送重复。
- 避坑：单例 SocketHub，所有 widget 订阅同一连接的 channel（见 05）。
10. WebSocket 没心跳，Nginx 60s 默认超时把连接掐了
- 现象：放着不动 60s 后再无数据更新。
- 避坑：客户端 25s 一次心跳；服务端 / Nginx
proxy_read_timeout调到 ≥ 90s。
11. 重连没指数退避，扎堆把后端打挂
- 现象：后端短暂抖动，几百块大屏一起 1s 重连，把后端二次压垮。
- 避坑：
3s → 6s → 12s → 24s，封顶 60s + jitter。
12. setInterval 轮询不等上次返回就发下一次
- 现象：网络慢时请求堆积，最后浏览器卡死。
- 避坑:用
setTimeout在请求 finally 后再排下一次。
13. 推送一来就 setState，60Hz 推送把 React 主线程榨干
- 现象：推得越快越卡。
- 避坑：在 Hub 层 RAF 节流合并；或用
useThrottledValue。
14. 时区不一致，跨夜大屏图表跳变
- 现象：23:59 → 00:00 时柱图跳一格，第二天的数据看着像第一天。
- 避坑：所有时间字段带时区/UTC；前端 dayjs.tz 统一转目标时区显示。
15. 后端字段类型不稳定，前端解析炸
- 现象：99% 是数字，偶尔来个
null/"--"，图表直接白屏。 - 避坑：service 层加 schema 校验（zod / valibot），异常值落兜底逻辑，不让脏数据扩散到组件。
16. 没有数据兜底，断网全屏白
- 现象：后端挂 5 分钟，整个大屏没东西。
- 避坑：每个 widget 显示「上次更新时间」+ 灰色「数据停滞」标签；保留最后已知值。
17. WebSocket 鉴权 token 暴露在 URL
- 现象：
?token=xxx写日志、写 referer，长期有效 token 泄漏。 - 避坑：连上后第一条消息发鉴权；或用短期 token + refresh。
三、渲染与可视化类
18. ECharts 实例没 dispose
- 现象：长跑两天内存涨 1G。
- 避坑：useEffect 清理函数
chart.dispose()，切换大屏时释放。
19. ECharts 频繁 setOption 用了 notMerge: true
- 现象：每次推送整图重画，CPU 满。
- 避坑：默认
notMerge: false, lazyUpdate: true；只更新变动的 series。
20. 用 SVG 画上万节点
- 现象：DOM 直接卡死。
- 避坑：> 500 节点切 Canvas；> 50000 切 WebGL（deck.gl / Three.js）。
21. 多个图表都监听 window.resize
- 现象：scale 容器尺寸变了，但 window 没变，图表不重绘。
- 避坑：用
ResizeObserver监听容器，不靠 window.resize。
22. Three.js 模型/纹理没释放
- 现象：切换场景后显存稳定上涨直到崩。
- 避坑：写
disposeObject工具函数；切场景前 traverse + dispose geometry/material/texture。
23. Three.js 阴影全开
- 现象：实时阴影在低端机直接 10fps。
- 避坑：阴影只给关键模型；用 baked 贴图 + fake AO 替代实时阴影。
24. 同屏多个 Three.js Renderer
- 现象：每个 3D 视口独立 renderer，性能直接乘 N。
- 避坑：一个 WebGLRenderer + scissor 多视口，或合并到同一场景按 layer 切换。
25. 地图底图请求被防火墙挡
- 现象：客户内网部署 Mapbox，瓦片 403 / 黑屏。
- 避坑：上私有部署的 MapLibre + tileserver-gl + 离线瓦片包；或国产高德/天地图。
26. Mapbox / 高德 token 写死前端
- 现象：被人盗用，账单暴涨 / 配额耗尽。
- 避坑：服务端代理签发短期 token，或绑定 referer + 域名白名单。
27. 飞线 effect 太多 ECharts 卡
- 现象：500 条飞线开 effect 后 25fps。
- 避坑：> 200 条改 deck.gl ArcLayer；纯展示场景关闭 effect。
28. 中国地图缺岛、缺南海
- 现象：领导看到了立刻发火。
- 避坑：用最新版 GeoJSON（带九段线）；上线前逐省检查一遍。
四、动画与视觉类
29. 全屏 Bloom + 粒子 + Lottie + 飞线全开
- 现象：开演后 30 分钟掉到 25fps，散热风扇拉满。
- 避坑：动效预算（07）；监控大屏一律关 Bloom。
30. 用 GIF 做动效
- 现象：体积大、循环卡顿、不能精细控制。
- 避坑：换 Lottie / video / canvas 动效。
31. Lottie 实例切换不 destroy
- 现象：日积月累内存涨。
- 避坑：组件卸载
anim.destroy()。
32. 闪烁告警 5Hz+
- 现象：刺眼，违反无障碍，可能诱发癫痫。
- 避坑：≤ 2Hz；红色 + 文字 + 图标三重表达，不仅靠颜色。
33. 数字滚动每帧 setState
- 现象：30 个 KPI 同时滚，主线程卡。
- 避坑：滚动逻辑放 ref + RAF，不触发 React 渲染；或用
react-countup。
34. GSAP 时间线没销毁
- 现象：切大屏后旧时间线还在跑，DOM 找不到报错。
- 避坑：组件卸载
tl.kill()；用gsap.context()自动管理。
35. 视频背景 autoplay 在浏览器被拦
- 现象：dev 正常、部署后视频不动。
- 避坑：必须
muted + playsinline；启动页放「点击进入」按钮触发首次播放。
36. 现场第一次跑完整动画
- 现象：调试 90% 都跑过，唯独完整时间线没合过，发布会卡在第 3 分钟。
- 避坑：上线前完整跑 3 次以上，含真实数据 + 真实大屏。
五、稳定性 / 长跑类
37. 没有 watchdog
- 现象：页面假死后没人发现，第二天领导问起才知道。
- 避坑：浏览器内自检（lastTickTs）+ Electron 主进程监控渲染进程；超时 reload。
38. 没有自动刷新策略
- 现象：跑一周内存花屏。
- 避坑：凌晨 4:00 全量 reload；新版上线 WS 推
reload命令。
39. ErrorBoundary 包整屏
- 现象：一个 widget 错全屏黑。
- 避坑：包到 widget 粒度，单个失败显示「该组件加载失败」。
40. 异步请求不带超时
- 现象：网关挂时 fetch 永远 pending，loading 转一晚上。
- 避坑：所有 fetch 配
AbortController，5~15s 超时。
41. setInterval 在标签页隐藏时被节流到 1Hz
- 现象：监控大屏被切到后台，回来一刷新数据全旧。
- 避坑：Electron 设
backgroundThrottling: false；浏览器靠后端补推或回前台立即重拉。
42. console.log / console.table 留在生产
- 现象：长时间运行后控制台几十万条，DevTools 内存爆。
- 避坑：构建剔除 console；监控大屏永远关 DevTools。
43. 监控探针频率过高
- 现象：每秒探一次，日志库被打爆。
- 避坑：30s 一次 + 关键事件即时上报。
六、部署与运维类
44. Chrome Kiosk 模式被 Esc 退出
- 现象：清洁阿姨碰一下键盘就回桌面。
- 避坑：
chrome --kiosk+ 屏蔽 Esc/Alt+F4/Ctrl+W；改 Electron 套壳更稳。
45. 浏览器自动更新引发不兼容
- 现象：客户机房 Chrome 自动升到 130，某 API 行为变了。
- 避坑：禁用自动更新；锁定版本；优先 Electron 套壳。
46. 没绑开机自启 / 自动登录 / 永不睡眠
- 现象：电源闪一下，第二天来发现屏黑了，要人工现场开机。
- 避坑：启动项 + BIOS 来电自启 + 自动登录 + 永不睡眠 + 永不锁屏。
47. 静态资源走公网 CDN
- 现象：客户内网偶尔抽风、CDN 抖动 → 大屏白屏。
- 避坑：所有 JS / 字体 / 图片 / 视频本地化，打进 Electron 包。
48. 没设置 cache-control，更新后大屏一直显示旧版
- 现象：刷新一万次还是旧的。
- 避坑：HTML 短缓存（no-cache），JS / CSS 长缓存（hash + immutable）。
49. 服务器时间漂移
- 现象：一台运维机时间慢 5 分钟，rrdtool 出现负值。
- 避坑：所有机器装 NTP；前端不要依赖
new Date()与服务端时间精确一致。
50. 没准备远程刷新通道
- 现象：大屏在外地，出问题要派人开车去现场。
- 避坑：内置
/reload接口；运维中台一键刷新；Electron + IPC 远程命令。
51. 大屏机被装了奇怪的输入法 / 杀软
- 现象：弹窗挡住大屏；输入法浮窗显示在角落。
- 避坑：独立账号最低权限；禁止安装；BIOS 锁 USB；Kiosk 全屏遮盖任务栏。
52. 部署完成没写交付文档
- 现象：原运维离职，没人会重启大屏。
- 避坑：交付包含重启步骤、登录账号、远程入口、刷新命令、应急联系。
七、协作与流程类
53. 设计师按桌面端体验出稿
- 现象：信息密度大、字号偏小、间距紧；远距离根本看不清。
- 避坑：和设计师对齐「8 米外阅读」原则；出稿后用 50% 缩略图自查（缩略图看不清就不及格）。
54. 后端按管理后台风格出接口
- 现象：分页 20 条、字段一堆 ID、不带名称。
- 避坑：大屏接口单独定，按「一次拉够、字段直接可展示」原则；前后端协议要写「冷字段不要返回」。
55. 数据接口在演示前还在改
- 现象：发布会前一天后端字段改名，前端临时改代码上线，崩了。
- 避坑：演示前 3 天接口冻结；任何改动走应急流程。
56. 没有演示模式（Demo Mode）
- 现象：现场断网，整屏白板。
- 避坑：内置 mock 数据 + 故事感曲线，断网也能演（03）。
57. 演示用的是开发环境
- 现象：领导讲话时
console.error一片红，权限弹窗冒出来。 - 避坑：演示走专用「演示环境」域名；提前清缓存、清通知、关插件。
58. 验收没写清谁签字
- 现象：客户现场不停加需求，永远收不了尾款。
- 避坑：签合同时把验收清单写死；额外需求走变更单。
59. 数据口径前后端不一致
- 现象：大屏显示「日活 12 万」，BI 报表是「日活 9 万」，被领导抓住。
- 避坑：所有指标在数据团队定义口径文档；前端只展示，不二次计算。
60. 没人负责长期运维
- 现象：上线即结项，三个月后大屏挂了没人管。
- 避坑：交付时明确值班人 + 监控群 + SLA；写在合同里。
八、安全与合规类
61. 大屏电脑没人管，被插 U 盘装游戏
- 现象：客户运维上去打了把游戏，大屏崩了。
- 避坑：BIOS 禁 USB；最低权限账号；远程审计。
62. 显示敏感数据时来了访客
- 现象：用户手机号、身份证全摆屏上。
- 避坑：设计「访客模式」一键脱敏；敏感字段默认
***，只在授权操作下展开。
63. 国产化要求被忽略
- 现象：交付前才发现客户要求信创（麒麟 OS、达梦库、龙芯/飞腾 CPU）。
- 避坑：投标阶段就确认；Electron 在飞腾上要测；某些图表库国产 OS 兼容性差。
64. 地图缺甲级测绘资质
- 现象：用了境外底图被审计。
- 避坑：政企/政府项目一律国产地图（高德/天地图/超图）；甲级资质找有牌照的服务商。
九、终极避坑「三件套」
不管什么大屏，至少做到：
- 演练 72 小时长跑：内存、FPS、连接数曲线平稳。
- 断网/断后端预案：拔网线照样有得看，恢复后能回填。
- 现场实测一遍：颜色、字号、远距离阅读、电源、自启、远程刷新，逐项打勾再走。
大屏翻车 80% 不是技术不行，是没去现场、没演练、没冻结接口、没写交付文档。
