Debug 日记

记录每一次踩坑，分享每一份解决方案

关于这个栏目

开发之路上，Bug 总是如影随形。这个栏目用于记录本站在开发与维护过程中遇到的真实问题、排查思路与最终解决方案。 每一条记录都来自实际踩坑经历，涵盖前端兼容性、PWA 缓存、JavaScript API、性能优化、后端跨域等方向。 希望这些经验能帮助遇到同样问题的开发者少走弯路，也作为自己的技术备忘录持续积累。

5 条踩坑记录 涵盖 前端 / PWA / JavaScript / 性能 / 后端 持续更新中

踩坑记录

CSS 变量在旧版 Safari 中不生效
2026-07-15 前端
在 Safari 14 之前的版本中，CSS 自定义属性（CSS Variables）在某些情况下无法正确继承，导致暗色主题切换失效。
解决方案： 使用 @supports 查询检测 CSS 变量支持，为不支持的浏览器提供回退值。同时使用 postcss-custom-properties 插件在构建时生成兼容代码。
CSS 兼容性 Safari
Service Worker 缓存导致页面更新不生效
2026-07-10 PWA
用户反馈站点更新后看不到新内容，排查发现 Service Worker 缓存策略过于激进，缓存了所有 HTML 页面且未设置正确的 max-age。
解决方案： 将 HTML 页面的缓存策略改为 Cache-Control: no-cache, must-revalidate，在 Service Worker 中使用 network-first 策略处理导航请求，确保用户始终获取最新版本。
PWA Service Worker 缓存
IntersectionObserver 在 file:// 协议下失效
2026-07-05 JavaScript
在本地使用 file:// 协议打开 HTML 文件时，IntersectionObserver 的回调不触发，导致 data-animate 元素永久隐藏。
解决方案： 添加 200ms 的 setTimeout 兜底机制，在 IntersectionObserver 创建后 200ms 强制将所有 [data-animate] 元素设为可见。同时检查协议，在 file:// 下直接显示所有动画元素。
JavaScript IntersectionObserver 动画
Google Fonts 在国内加载502错误
2026-06-28 性能优化
使用 Google Fonts (fonts.googleapis.com) 导致页面在加载时出现 502 错误，严重影响中国用户的访问体验。
解决方案： 将字体源从 fonts.googleapis.com 切换到国内镜像 fonts.googleapis.cn 和 fonts.gstatic.cn，同时添加 font-display: swap 确保字体加载期间文字可见。
字体 性能优化 CDN
relative API 路径导致 CORS 跨域错误
2026-06-20 后端
analytics.js 中使用相对路径发送 API 请求，在跨域部署时请求被发送到前端域名而非 API 服务器，导致数据收集不完整。
解决方案： 将所有 API 请求路径改为绝对路径 https://api.ppdxpz.com.cn/api/...，在 API 服务器端配置正确的 CORS 头，允许前端域名的跨域请求。
API CORS 跨域