别让一个浏览器毁掉你的上线：vibe 项目的浏览器兼容与渐进增强实战

先说清楚：这篇讲什么，不讲什么

你的项目在自己的 Chrome 里跑得好好的，上线第一天就收到反馈：同事的 Safari 上按钮点不动，用户的旧安卓手机上页面一片空白，火狐上排版错位到没法看。这不是用户设备的问题，这是上线前少做了一件事：浏览器兼容。

本文讲的就是这一件事：一个人或小团队怎么做浏览器兼容，才能不被它拖垮，也不被它吓住。核心方法只有一个：渐进增强。先保证最基础的功能在所有浏览器里都能用，再给能力更强的浏览器叠加更好的体验。顺序不能反。

划界先说清楚，避免和站内已发指南重复：移动端适配指南讲的是小屏幕下的布局与交互怎么做顺手；暗色模式指南讲的是主题切换；无障碍指南讲的是残障用户能不能用。本文不重复这三点，只讲浏览器之间的能力差异：同一个功能，在 Chrome、Safari、火狐、Edge 和各类手机浏览器里，表现不一样时怎么办。本文也不讲 PWA 安装，那是另一篇指南的主题。

文中的示例产品“白鹭清单”和人物“林晓”均为虚构示例，仅用于讲清楚做法，不代表真实产品与真实用户。下文所有代码片段均为教学示例，可直接改写后用于自己的项目，但上线前仍需在自己的目标浏览器里实测。

第一步：先定兼容基线，而不是先写代码

很多人做兼容是从修 bug 开始的：哪里报错修哪里。这是最累的做法。正确顺序是先定基线，再写代码，最后按基线验收。基线就是一句话：你的项目要支持到哪些浏览器，以及在每个档位上要保证到什么程度。

一人团队不需要搞复杂的分级，定两档就够了。第一档叫核心可用：页面能打开、能读内容、能完成主流程，比如注册、创建、保存、支付意向提交。第二档叫完整体验：动画、毛玻璃、拖拽、高级选择器这些加分项，在支持的浏览器里出现，在不支持的浏览器里安静缺席，但不能让主流程跟着一起坏。

定基线要看真实数据，不要凭感觉。已经有用户的项目，直接看统计里的浏览器分布：前 95% 的流量覆盖到哪些浏览器版本，就以此为基线。还没有用户的项目，可以用一个保守起点：近两年的 Chrome、Edge、火狐、Safari 正式版，外加 iOS Safari 和主流安卓浏览器。写进项目说明里，比如用 browserslist 写一行配置，让构建工具和自动加前缀的工具都按同一份基线工作。基线一旦定下来，就不要在开发中途随手放宽或收紧，改基线要改文档、改测试清单，一起改。

还有一个判断要提前做：像素一致不是目标。不同浏览器对字体渲染、滚动条、表单控件的默认样式本来就不一样，追像素一致会把时间烧光。目标应该是功能一致、信息一致、主流程一致。按钮圆角差两像素可以接受，按钮点不动不能接受。把这句话贴在团队共识里，能省掉很多无意义的争论。

第二步：按三层写，而不是按浏览器写

渐进增强的三层，写起来其实很朴素。第一层是 HTML：内容本身、语义标签、原生表单控件、链接和按钮。这一层不依赖 CSS 和 JavaScript，是兜底。第二层是 CSS：布局、颜色、动效，在支持的浏览器里变好看。第三层是 JavaScript：交互、动态加载、高级能力。每一层都只在上一层可用的前提下加分，绝不能让上一层成为下一层的单点故障。

举一个虚构例子。林晓的“白鹭清单”要做一个新建任务的对话框。最底层，她先用原生的对话框元素和表单写出来：能打开、能输入、能提交，关掉 JavaScript 也能靠表单提交完成创建。第二层，她用 CSS 把对话框做得好看一点。第三层，她才用 JavaScript 加上快捷键、自动聚焦、按 Escape 关闭这些体验。结果是：在最老的环境里，用户得到一个朴素但能用的对话框；在现代浏览器里，用户得到完整体验。没有任何一个浏览器会因为第三层失败而丢掉第一层。

这个顺序还有一个好处：它逼你先想清楚主流程。很多 vibe coding 项目的问题不是兼容，而是主流程本身就绑死在某个高级 API 上。比如整个创建流程只用拖拽完成，没有按钮备选；或者整个页面只靠 JavaScript 渲染，脚本一失败就是白屏。先写 HTML 层，等于先给主流程买了一份保险。

判断一个功能是不是写反了，有个简单方法：关掉 JavaScript，再关掉 CSS，看页面还剩什么。如果还剩可读的内容和可走的主流程，结构就是对的。如果只剩白屏或一堆错位的盒子，说明增强层绑架了基础层，要先拆开再往下做。

第三步：能力检测代替浏览器嗅探

这是本文最重要的一条纪律：不要通过用户代理字符串去判断浏览器，再写一堆 if-else 分支。用户代理可以伪造、会变化，而且你判断的是浏览器名字，不是能力本身。今天 Safari 支持了某个 API，你去年写的分支还在把它当成不支持，白白降级；明天某个新浏览器出现，你的分支根本认不出来。

正确做法是直接检测能力。CSS 里用 @supports 判断浏览器支不支持某个属性或选择器，支持就用增强写法，不支持就走基础写法。JavaScript 里直接判断对象或方法存不存在，比如判断某个接口在不在 navigator 上、某个方法在不在元素原型上。能力存在就用，不存在就降级或换一条路。

代码写起来是这个样子。先是 CSS 的能力检测：先写所有浏览器都能理解的基础布局，再在 @supports 里写增强布局。基础布局用弹性盒子就能完成两列，支持网格布局的浏览器再升级成更复杂的网格。这样写的好处是，旧浏览器读不懂 @supports 里那一段时会自动跳过，而不是报错。JavaScript 也一样：先判断剪贴板写入接口是否存在，存在就用它，不存在就退回到选中文本加手动复制提示。用户得到的永远是“能用的次优解”，而不是报错弹窗。

需要特别提醒的是动态加载。体积大的增强功能不要一股脑打进首屏包里，检测到能力、并且用户真的需要时再动态引入。比如高级图表、富文本编辑、复杂动效，都可以等用户进入对应页面或点击对应功能时再加载。这样既照顾了低端设备，也让首屏更快。反过来，把所有增强都塞进首屏，是兼容和性能的双重负担。

第四步：高频坑位清单，照着查一遍

下面这些坑，是小团队最容易反复踩到的。不是说每个项目都会全踩中，而是上线前值得逐条问一句：我这个项目有没有用到它。

第一组是视口与高度。移动端浏览器里，地址栏的显隐会让视口高度来回变化，用固定视口高度单位写全屏布局，很容易出现底部被遮住或留白跳动。做法是优先用动态视口单位，并给不支持的浏览器留一个基础高度兜底。写完一定要在真机上上下滑动页面看一遍，模拟器里地址栏行为和真机并不完全一样。

第二组是表单。日期、时间、颜色、文件这些原生输入控件，在不同浏览器里的外观和行为差异很大。不要假设所有浏览器都长一个样，也不要为了统一外观就把原生控件全部换成自绘组件。自绘组件要自己补键盘操作、焦点管理、无障碍语义，成本远高于想象。更稳妥的做法是：保留原生控件，只做轻量美化，把自绘留给确实需要自定义交互的少数场景。

第三组是 Safari 的特殊行为。iOS Safari 对自动播放、剪贴板、文件选择、第三方 Cookie、弹窗都有自己的限制，很多在桌面 Chrome 里顺畅的流程，到 iOS 上会被拦截或要求用户手势触发。涉及这些能力的流程，一定要设计成“用户点一下才触发”，并且给被拦截的情况准备一句人话提示，而不是让用户对着没反应的按钮发呆。桌面 Safari 也有自己的节奏，某些新 CSS 能力上线会晚于 Chrome，写增强样式时务必用 @supports 包住。

第四组是权限类 API。剪贴板、通知、地理位置、摄像头这些能力，都需要用户授权，而且授权状态、提示时机在不同浏览器里不一样。正确姿势是：在用户明确操作的上下文里再申请权限，申请前先用一句话告诉用户为什么需要，申请被拒绝后提供手动替代路径。页面一加载就连珠炮式申请权限，是最容易被用户和浏览器双双拒绝的做法。

第五组是滚动与动效。平滑滚动、滚动吸附、视图过渡这些效果，在不同浏览器里的支持度和默认行为都不一样。动效一律要当成增强：关掉动效后页面仍然完整可用，并且要尊重用户“减少动态效果”的系统设置。动效写得再好看，也不能以牺牲可读性和主流程为代价。

第五步：一人团队的测试矩阵，30 分钟版

小团队做不了全量兼容测试，但可以做一个 30 分钟的冒烟矩阵，覆盖最容易出事的组合。准备三台视角就够了：一台桌面 Chrome、一台桌面 Safari 或火狐、一台真机（iOS 或安卓，至少一种）。如果只有一台电脑，就用浏览器的设备模拟加一款真机浏览器补位。目标不是测遍所有组合，而是保证主流程在三类环境里都走得通。

测试清单可以固定下来，每次发版前走一遍：首页能不能打开、能不能注册登录、能不能完成一次核心创建、能不能保存后刷新还在、表单报错能不能看到、按钮在触屏上点不点得到、长页面滑到底有没有内容被遮住。每一项在三类环境里打勾，任何一项在某一类环境里失败，都先修主流程，再谈美化。

自动化可以帮你省掉重复劳动，但要量力而行。用 Playwright 这类工具跑一套跨浏览器冒烟测试，覆盖 Chromium、Firefox、WebKit 三个引擎的主流程，是性价比最高的投入。截图对比可以做，但阈值要放宽，只拦布局崩坏和内容丢失，不要拦像素差异。自动化测的是“没坏”，不是“长得一样”，把这个标准写进测试说明里，团队才不会被误报拖垮。

还有一个低成本做法：把浏览器的报错当成发版信号。上线前打开各浏览器的控制台走一遍主流程，看到报错先分类：是增强功能失败，还是主流程失败。增强失败可以降级处理，主流程失败必须修掉再发。这个习惯比买任何测试服务都管用，因为它逼你在发版前亲眼看过真实环境。

第六步：让 AI 先交基础层，再谈增强

vibe coding 有一个特有的兼容风险：AI 生成代码时，默认按最新、最顺手的写法来，经常一上来就用刚发布不久的接口和选择器，还把整个页面写成客户端渲染。等你发现旧浏览器打不开时，返工量已经很大了。与其事后修，不如在提示词里就把兼容顺序写死。

一个可直接用的做法是：给 agent 的任务开头加三条硬约束。第一，先交不依赖 JavaScript 也能走通的主流程，再叠加交互。第二，增强样式必须用能力检测包住，不许直接写只有新浏览器才懂的写法当成默认样式。第三，凡是用到较新接口的地方，必须同时给出降级路径，并写明降级后用户还能做到什么。这三条写进任务描述，比事后让 agent“修一下兼容”要有效得多，因为事后修往往只是在坏结构上打补丁。

审查 AI 交出来的代码时，也按三层来审。先看 HTML 层：内容在不在、语义对不对、表单能不能原生提交。再看 CSS 层：基础布局有没有脱离增强写法独立成立，有没有把新特性当成唯一布局手段。最后看 JS 层：有没有在调用新接口前检测能力，有没有把失败分支写出来。很多 AI 生成的代码在“能跑”这个标准下是满分，在“坏了还能用”这个标准下是不及格的，审查标准要改过来。

还有一个容易被忽略的点：依赖与构建配置。AI 可能会顺手引入一个只支持现代浏览器的组件库，或者把构建目标设成最新版本，导致转译和前缀都没做。接手这类代码时，先检查构建目标与基线文档是不是同一份，再检查组件库的浏览器支持声明。构建配置与基线不一致，写再好的渐进增强代码也会被构建环节绕过去。

反模式：这六种做法，看到就停手

第一，只在 Chrome 里测完就上线。这是最常见的翻车原因，你的用户不只用 Chrome。第二，用用户代理字符串写分支逻辑，理由前面已经讲过：判断名字不如判断能力。第三，为了兼容一个小众能力，把整套 polyfill 全量引入，首屏体积翻倍，得不偿失。正确做法是只补自己用到的缺口，并且定期清理不再需要的补丁。

第四，用 CSS 奇技淫巧硬凑像素一致，结果代码里堆满浏览器专属 hack，下一个人根本不敢动。第五，遇到不支持就整页拦截，弹一句“请使用 Chrome 访问”。拦截只在极少数场景下合理，比如确实依赖某个浏览器专属能力且没有替代路径的产品；对绝大多数内容型和工具型项目，拦截等于把用户往外推。第六，把兼容问题推给用户，让用户自己去升级浏览器、清缓存、关插件，而不在产品里给降级路径。用户没有义务为你的兼容缺口买单。

取舍判断：什么时候可以放弃旧浏览器

放弃旧浏览器不是技术决定，是成本决定。判断标准有三条。第一，看数据：这个浏览器版本带来的真实用户占比是不是已经低到可以忽略，以及这些用户是不是你的核心用户。第二，看代价：为了支持它，要不要牺牲主流程的开发速度、引入高风险的补丁、拖慢所有用户的首屏。第三，看替代路径：放弃之后，这些用户能不能通过基础版本继续用核心功能，还是会被彻底挡在门外。

如果三条都指向可以放弃，做法也不是悄悄下线，而是体面降级。给受影响的用户一句诚实提示：你的浏览器版本较旧，部分新功能可能无法使用，但核心功能仍然可用，并附上升级建议链接。不要用恐吓式文案，不要伪造安全风险逼用户升级。体面降级既保护了老用户，也给团队省下了维护成本。

最后留一张上线检查表，照着打勾就能发版。基线写进文档了吗。主流程关掉 JavaScript 还能走吗。增强样式都用能力检测包住了吗。表单、视口、权限这三组坑查过了吗。三类环境的主流程冒烟跑过了吗。控制台没有主流程报错了吗。降级提示写的是人话吗。七项全过，再点发布。兼容不是上线前的一次性冲刺，而是每次发版前的一张固定清单。清单越固定，翻车越少。