uni-app X + Spring Boot 做在线工具站:6 个真实踩坑与解法

我做了一个自用的小工具站(锐影工具集市),把平时高频用的十几个小工具收在一个页面里:前端用 uni-app X(uvue)编译 H5 ,后端 Spring Boot 3 + MyBatis-Plus + MySQL ,nginx 静态托管 + /api 反代,部署在宝塔面板上。目前站内 19 个工具(18 个网页小工具 + 1 个微信小程序)、3 个分类,全部自己开发维护。

功能本身不难写,真正花时间的是上线后接二连三暴露的坑:刷新 404、白屏、内容隐身、校验假通过。这些坑有个共同点------本地跑全绿,一到线上或换个环境就发作,而且大多不报错。

这篇文章把 6 个最值钱的坑整理出来,每个按「现象 → 原因 → 解法 → 教训」讲,文末附效果展示和项目信息。

坑 1:history 路由上线后,一刷新就 404

现象:本地怎么跑都没事,部署后首页正常,但任意页面一刷新(或直接粘贴子页面链接打开),服务器返回 404。

原因 :项目最初用 hash 路由(URL 长成 /.../#/pages/tools/count),改成 history 路由后 URL 变干净了,但刷新时浏览器请求的是真实路径,nginx 上并没有这个文件。

解法 :让 nginx 把未知路径统一回退到 SPA 外壳,同时静态资源目录单独 404------不然资源名写错时会被 index.html 的 200 掩盖,问题被藏到下一层:

bash 复制代码
location /assets/ { return 404; }
location /static/ { return 404; }
location / {
    try_files $uri $uri/ /opt/ruixing/h5/index.html;
}

教训 :SPA 换路由模式不是前端一个人的事,路由模式是前后端的契约,改它的那天就要同步改服务器配置。

坑 2:整站迁到 /tools/ 子路径,构建全绿、线上白屏

后来根路径要让给别的站点,整站从 / 迁到 /tools/。构建配置里把 base 改成 /tools/ 之后,打包资源确实都带上了前缀------但线上还是白屏。真正的问题有三个,一个比一个隐蔽:

  1. 运行时字符串不会被加前缀。 代码里手写的 return '/static/img/x.png'、iframe 地址常量,构建器不会碰它们,必须自己写死 /tools/static/...,否则分类空态图和两个 iframe 工具直接 404。
  2. 反过来,模板里的路径不能加前缀。 <image src> 与样式里的 url() 必须保持 /static/ 原样------写成 /tools/static/ 会让打包器去解析一个不存在的模块,构建直接失败 (Rollup failed to resolve import "/tools/static/img/empty-data.png")。
  3. nginx 要用 alias 而不是 root。 root 会把 /tools/assets/x 拼成 <root>/tools/assets/x,多出一层;而且 alias + try_files 的回退目标必须写绝对路径 ,写 /index.html 又绕回去了。

教训 :子路径部署要建立一个心智模型------构建期路径和运行时路径是两套世界观 。构建期的 base 归打包器管,运行时的字符串归你自己管,两边的规则甚至相反。上线前把「手写路径」全局搜一遍,比任何文档都管用。

坑 3:uni-app X 里用 try/catch 校验 JSON,是假通过

站里有个 JSON 格式化工具,需要判断用户输入是否合法。惯性写法是 try { JSON.parse(x) } catch { 非法 },本地测试也正常------直到发现非法输入被报成"语法有效",还输出了 null。

原因 :uni-app X 的编译器会把 JSON.parse 改写成 UTS.JSON.parse,它在 H5 端的实现遇到语法错误不抛异常 ,只 console.error 再返回 null。你的 catch 分支永远进不去。

解法 :不再依赖异常,改用哨兵判断------解析结果是 null 但原文不是字符串 null,那就是非法;再补一次结构扫描给出出错位置:

ini 复制代码
const val = UTS.JSON.parse(text)   // 失败返回 null,不抛异常
const illegal = val === null && text.trim() !== 'null'
// illegal = true 时,报告"输入不是合法 JSON"

教训 :跨端框架对标准 API 的 polyfill 行为差异,不会在编译期报错,只在运行期说谎。涉及"判断合法/非法"的逻辑,别信异常路径,自己留一个可观测的哨兵。

坑 4:sticky 顶栏静默失效,凶手是框架的 overflow:hidden

管理页做了个左侧锚点导航,position: sticky 写得没问题,本地也正常------上线后滚动时导航跟着页面跑没了。

原因 :uni 的基础样式给每个 uni-view 都写了 overflow: hidden。sticky 的吸附对象变成了那个不能滚的父容器,于是静默失效 :不报错、控制台干净,只是"没反应"。同一族的坑还有:元素靠 transform: scale() 放大出圈时,会被自己的盒子裁掉边缘------品牌标最初是 10px 圆点加 scale(1.35),用户看到的是"圆被挡住一块"。

解法 :给 sticky 的链路祖先显式加 overflow: visible,并把「必须带 overflow:visible」写成断言放进验证脚本,防止哪天重构被顺手"优化"掉。

教训 :框架级的全局样式是沉默的默认值。失效时没有任何报错,这类 bug 的排查成本最高------把修好的不变量固化成脚本断言,比写在文档里可靠。

坑 5:滚动显现动画,观察器一失灵内容就永久隐身

首页各分区用 opacity: 0.001 打底,靠 IntersectionObserver 进入视口时揭示。本地一切正常,直到有一次用无头浏览器整页截图:除了首屏,下面全是空白。

原因 :观察器没触发(或回调异常)时,内容就永远停在 opacity: 0.001------页面"加载成功",只是什么都看不见。

解法,两层兜底:

javascript 复制代码
function revealSection(el) {
  try {
    io.observe(el)
  } catch (e) {
    el.style.opacity = 1          // 观察器异常:直接显示
  }
  setTimeout(() => { el.style.opacity = 1 }, 1200)  // 无论如何 1.2s 后现身
}

外加两条配套纪律:

  • 循环动画必须在 prefers-reduced-motion: reduce) 里逐个点名关掉 。全局兜底样式编译后只覆盖框架标签,挂在原生 <svg> 上的动画它管不到,得自己列清单。
  • 带 filter: blur() 的元素只许平移 ,不要叠加 scale------每帧重新栅格化,will-change 的层缓存是白给的。

教训 :所有"默认隐身、按需现身"的设计,必须回答一个问题:揭示机制失效时用户看到什么? 答案如果是"白屏",这个设计就不及格。

坑 6:打开计数这种旁路请求,别混进主数据流

首页要统计"每个工具被打开多少次",做法是点击卡片时 POST /api/tools/{id}/open。最初它和工具列表一起写在主请求里,一次统计接口抖动,首页直接进错误态。

解法 :把计数请求刻意留在主数据流之外,并且不写 fail 回调:

php 复制代码
// 主请求:失败要报错、要重试
fetchAll()
// 旁路计数:发出去就不管了
fetch('/api/tools/' + id + '/open', { method: 'POST' })

后端侧用数据库端原子自增(open_count = open_count + 1),不读-改-写;编辑工具时显式把计数字段置 null 交给数据库保留,避免被表单覆盖清零。

教训 :丢一次计数只是少算一次,不该把主流程拖进错误态。 判断一个请求该不该进主数据流,就问:它失败了,用户需不需要知道?不需要的,全部降级为旁路。

把"改完不放心"写成脚本

上面这些坑有个共性:改的时候对,跑起来才错。所以这个项目最后沉淀了一套 Node 验证脚本,部署前全量跑:

  • 产物级断言 300+ 项:路由模式、子路径 base、深链回退、资源 404、鉴权头不泄漏......
  • 可访问性审计 85 项、布局实证 88 项(375/768/1440/1920 四个宽度)
  • 18 个工具页逐页行为探针 275 项:每个页面单独挂载,断言真实计算结果

还有一条容易忽略的:夹具会过期。从活体站点刷出来的接口快照,工具条数一变就变成对着过期数据断言,全绿也是假绿------夹具要提供一键从线上刷新的脚本。

几点思考

  1. 框架的便利和暗坑是同一份礼物。 overflow:hidden、路由 base、JSON 改写,便利性越高,默认值越沉默。用框架时要养成一个习惯:它"自动"帮你做的事,问一句它没管什么。
  2. 本地全绿不是证据,只是还没到发作条件。 环境差异(history、子路径、无头浏览器)才是大多数 bug 的显影液,上线前专门在"最像生产的环境"里过一遍。
  3. 给所有隐身式设计配兜底,给所有旁路请求降级。 这两条是这个项目里性价比最高的防线,也是我这次最大的收获。

效果展示

站点首页最终效果(19 个工具、三类分区,截图拍摄于 2026-11-17):

项目信息

项 内容
前端 uni-app X(uvue)→ H5,零第三方 UI 库,图标 Phosphor 内联 SVG
后端 Spring Boot 3 + MyBatis-Plus + MySQL,REST 统一 {code, data, msg}
部署 nginx 静态托管 + /api 反代,宝塔面板管理
质量 Node 验证脚本 300+ 断言,部署前全量回归
线上地址 reying.cc/tools/

如果正在做同类站点,欢迎在评论区交流你的解法。

相关推荐
掘金挖土12 分钟前
前端手摸手跑路之 AI 应用开发(十二)
前端·后端
颜进强13 分钟前
微信里冒出一个新 AI 入口,我们把接入它的每一步坑都写下来了
前端·ai编程
不要试图纠正别人13 分钟前
178 个 IPC 通道不可怕,可怕的是 preload 里那一行
前端·electron
bai27316 分钟前
Node 22 里的等待:从回调到 Promise,一次上传流程的最小记录
前端
__sjfzllv___16 分钟前
在职前端Leader学习/转行 AI Agent -DAY104
前端
花椒技术22 分钟前
从 AI Demo 到直播间上线:全场一起猜的接入、排错与验收
前端·ai编程
花椒技术1 小时前
一名前端借助 AI ,6天把【神兔之争】游戏做进直播间
前端·ai编程
孟健1 小时前
用 HyperFrames 解决前端视频生成难题:国产 Flash 模型实测 3 条 1080p 视频
前端·人工智能·开源
super_Omni2 小时前
突破前端防御重围:现代 Web 媒体资产嗅探、CDN 逆向还原与反爬破壁架构实战
前端·架构·媒体