Safari兼容性问题需先排除缓存干扰，再通过开发者工具控制台查ES6语法报错、Computed面板验证CSS声明是否被静默丢弃，并用Xcode模拟器真机调试定位渲染差异。
当你在 Safari 浏览器中打开前端页面，发现布局错乱、交互失效、样式不渲染或直接白屏，却在 Chrome 或 Firefox 中一切正常，说明页面存在 Safari 特定的兼容性问题，必须通过可复现、可验证、可定位的路径来排查。
确认是否真为 Safari 兼容性问题
先排除网络、缓存、插件干扰：在 Safari 地址栏输入 safari://clearhistory 清空全部历史记录与缓存 → 打开「开发」菜单（若未显示，需在「偏好设置→高级→勾选“在菜单栏中显示开发菜单”」）→ 选择「清除缓存」→ 重启 Safari 并重新加载页面。
如果问题依旧，再进入下一步；若页面恢复正常，说明是缓存导致资源未更新，不是兼容性问题。
快速定位报错源头
打开 Safari 开发者工具（开发 → 在当前页启用开发者工具）→ 切换到「控制台」标签页 → 刷新页面。
立即学习“前端免费学习笔记（深入）”；
重点查看红色错误行：若出现 Unexpected token 'const'、Invalid regular expression 或 ReferenceError: Can't find variable: Promise，说明是 ES6+ 语法或 API 在低版本 Safari（如 iOS 12.5 / Safari 12）中不被支持；若出现 TypeError: undefined is not an object (evaluating 'xxx.style.transform')，大概率是 DOM 节点未正确获取或 CSS 属性名拼写错误。
【注意】iOS 15.4 之前 Safari 不支持 aspect-ratio 无前缀写法，但加 -webkit-aspect-ratio 也无效——该属性根本不存在，必须用 padding-top 百分比模拟。
模拟真实设备环境
第一步：打开 Xcode → Preferences → Components → 下载对应 iOS 版本的 Simulator（如 iOS 13.7、iOS 14.8）；
第二步：启动模拟器 → 打开 Safari → 输入本地开发地址（需确保 Mac 与模拟器在同一局域网，且 Web 服务监听 0.0.0.0:3000 而非 localhost:3000）；
第三步：在模拟器中 Safari 地址栏输入 debugger → 回车 → 自动触发断点，此时 Safari 开发者工具会连接到该页面，可实时调试 JS 执行流、审查元素、监听网络请求。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
这一步不可跳过：真机或模拟器环境才能暴露 iOS Safari 独有的渲染行为，比如 position: sticky 在父级有 transform 时完全失效，而桌面 Safari 可能表现正常。
针对性验证 CSS 兼容性
方法一：用 @supports 检测特性是否可用
在开发者工具控制台粘贴执行：getComputedStyle(document.documentElement).getPropertyValue('backdrop-filter') !== ''，返回 '' 表示 backdrop-filter 未生效；
方法二：查 caniuse.com 精确到 Safari 版本
搜索目标特性（如 overscroll-behavior），确认「Safari on iOS」列中标绿的最早版本（例如 iOS 16.4 支持），若你需兼容 iOS 15.6，则该特性必须降级为 overflow: hidden + 手动阻止滚动事件；
方法三：手动添加 WebKit 前缀并观察是否修复
仅对明确标注「Only with prefix」的属性才加，例如 -webkit-line-clamp，其他如 flex、grid、gap 等现代属性加前缀反而可能被忽略——【iOS 16.4+ 已移除对 -webkit-flex 的支持】。
检查构建配置是否覆盖目标 Safari 版本
打开项目根目录下的 .browserslistrc 文件，确认包含类似 ios_saf >= 12.2 或 safari >= 13 的声明；
运行命令 npx browserslist "ios_saf >= 12.2"，输出中必须含 Safari 版本号，否则 Babel / Autoprefixer 不会注入兼容代码；
若使用 Vite，还需检查 vite.config.ts 中 build.target 是否设为 'safari12' 或更低——设为 'modules' 将默认忽略 Safari 旧引擎。
