我做了一个自用的小工具站(锐影工具集市),把平时高频用的十几个小工具收在一个页面里:前端用 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/ 之后,打包资源确实都带上了前缀------但线上还是白屏。真正的问题有三个,一个比一个隐蔽:
- 运行时字符串不会被加前缀。 代码里手写的
return '/static/img/x.png'、iframe 地址常量,构建器不会碰它们,必须自己写死/tools/static/...,否则分类空态图和两个 iframe 工具直接 404。 - 反过来,模板里的路径不能加前缀。
<image src>与样式里的url()必须保持/static/原样------写成/tools/static/会让打包器去解析一个不存在的模块,构建直接失败 (Rollup failed to resolve import "/tools/static/img/empty-data.png")。 - 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 项:每个页面单独挂载,断言真实计算结果
还有一条容易忽略的:夹具会过期。从活体站点刷出来的接口快照,工具条数一变就变成对着过期数据断言,全绿也是假绿------夹具要提供一键从线上刷新的脚本。
几点思考
- 框架的便利和暗坑是同一份礼物。
overflow:hidden、路由 base、JSON 改写,便利性越高,默认值越沉默。用框架时要养成一个习惯:它"自动"帮你做的事,问一句它没管什么。 - 本地全绿不是证据,只是还没到发作条件。 环境差异(history、子路径、无头浏览器)才是大多数 bug 的显影液,上线前专门在"最像生产的环境"里过一遍。
- 给所有隐身式设计配兜底,给所有旁路请求降级。 这两条是这个项目里性价比最高的防线,也是我这次最大的收获。
效果展示
站点首页最终效果(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/ |
如果正在做同类站点,欢迎在评论区交流你的解法。