先说问题:AI 写前端,为什么总是一股「老味」
让编程助手写个弹窗,它给你手写遮罩层、焦点管理和关闭动画,洋洋洒洒两百行 JavaScript——可浏览器早就有了原生的 <dialog> 元素和 Popover API,几行代码的事。让它做个响应式卡片布局,它掏出一套媒体查询加浮动兜底,而容器查询(Container Queries)已经全线浏览器支持好几年了。
这不是模型「笨」,是两个结构性原因:
- 训练数据里旧代码太多。大模型的语料横跨二十多年的 Web 开发史,老派写法在数量上碾压现代写法。模型按概率续写,自然优先吐出它见得最多的那一套:用一堆 JS 重造平台早就原生支持的轮子。
- 知道 API 存在,不等于会写生产级代码。就算模型「知道」某个新 API,它脑子里也缺少真实项目里那种高密度的现代实现范式——边界情况怎么处理、兜底怎么写、和无障碍怎么配合。知道和会用之间,差着一层专家经验。
本篇主线:认识一个专门补这层经验的技能包——Modern Web Guidance。它不换模型、不改提示词技巧,而是把 Web 平台的专家指南和浏览器兼容数据直接嵌进编程助手的上下文里,从源头把助手往现代写法上带。
它是什么:四家一起维护的「现代 Web 教练」
Modern Web Guidance 是一套给编程助手用的技能(Skills),由 Google Chrome 团队牵头,Microsoft Edge、Mozilla Firefox 与 MDN 团队共同维护,再加上 Web 开发社区的贡献。这个出身很重要:指南内容不是某个博主的心得,而是浏览器厂商和文档标准方的一手口径——哪些特性已经 Baseline 全线可用、哪些还在实验阶段,他们最清楚。
它干的事可以拆成三块:
- 现代浏览器 API 的正确结构:专门纠正模型最容易用错的那批 API,给出规范的写法骨架。
- 性能与无障碍优先:优先推荐能被浏览器底层优化、且自带无障碍语义的平台级方案,而不是 JS 模拟出来的效果。
- 负责任的兜底:新特性用不了的老浏览器怎么办,它给的是轻量、针对性的小兜底,而不是动不动引一个重型 polyfill 或老牌类库。
它和本系列上一篇的 Skill Seekers 是互补关系:Skill Seekers 是把任意文档炼成技能的「加工厂」,Modern Web Guidance 则是浏览器厂商亲自下场、已经炼好的「成品技能」——一个造技能,一个直接是技能。
快速开始:装上,或者先白嫖三条命令
安装走交互式向导,一条命令:
npx modern-web-guidance@latest install向导会识别你在用的编程助手并把技能装到位。后续更新同样简单:
npx modern-web-guidance@latest update不想装?它的 CLI 本身就能直接试,三条命令覆盖三个典型动作。
第一条:搜指南。 用自然语言描述你想做的事,它返回最相关的指南:
npx modern-web-guidance@latest search "animate a dialog modal backdrop"第二条:按 ID 取指南全文。 搜索结果里拿到指南 ID 后,把完整指南(代码范式、坑点、兜底写法)取出来读:
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"第三条:扫代码库里的遗留模式。 对着一个老项目跑一遍,它会指出哪些写法可以用现代平台能力替换——这是给存量项目做现代化盘点最顺手的入口:
npx modern-web-guidance@latest legacy-scan .除了官方安装器,它还适配了几乎所有主流助手的分发方式,挑你顺手的:
# Vercel Skills CLInpx skills add GoogleChrome/modern-web-guidance
# GitHub CLIgh skill install GoogleChrome/modern-web-guidanceClaude Code、Codex 等则有各自的插件市场装法(仓库 README 里有逐个助手的命令清单)。安装时还能用 --choose 只选需要的技能包:主包 modern-web-guidance 管现代 API、布局与性能,另一个 chrome-extensions 包专管 Chrome 扩展开发(Manifest V3、后台 Service Worker、扩展 API 与上架发布)。
安装与分发大全:每家助手都有自己的装法
快速开始里给的是「通用入口」,但这个技能包的分发做得相当全:仓库里同时带了 Claude Code、Codex、Cursor、Grok 等助手的插件清单文件,还有 Gemini 的扩展清单。按你用的助手对号入座:
| 安装方式 | 命令或入口 | 适合谁 |
|---|---|---|
| 官方安装向导 | npx modern-web-guidance@latest install | 不确定装哪种时用它,向导会识别你的助手 |
| Vercel Skills CLI | npx skills add GoogleChrome/modern-web-guidance | 已经在用 skills 生态统一管技能的人 |
| GitHub CLI | gh skill install GoogleChrome/modern-web-guidance | 习惯用 gh 管一切的人 |
| Claude Code 插件 | /plugin marketplace add GoogleChrome/modern-web-guidance 后 /plugin install modern-web-guidance@googlechrome | Claude Code 用户,可在插件菜单里开启 AutoUpdate |
| OpenAI Codex 插件 | codex plugin marketplace add GoogleChrome/modern-web-guidance 后 codex plugin add modern-web-guidance@googlechrome | Codex 用户 |
| GitHub Copilot CLI 插件 | /plugin marketplace add GoogleChrome/modern-web-guidance 后 /plugin install modern-web-guidance@googlechrome | Copilot CLI 用户 |
| Google Antigravity | agy plugin install https://github.com/GoogleChrome/modern-web-guidance | Antigravity 用户 |
| Grok Build CLI | grok plugin install https://github.com/GoogleChrome/modern-web-guidance --trust | Grok Build 用户 |
| Kimi Code | /plugins install https://github.com/GoogleChrome/modern-web-guidance | Kimi Code 用户 |
装的时候还有个选择题:技能包要装哪个。用 --choose 可以挑:
npx modern-web-guidance@latest install --choosemodern-web-guidance(主包,技能描述约 205 tokens):现代浏览器 API、布局与性能的全面指南,做网站就装它。chrome-extensions(约 175 tokens):专管 Chrome 扩展开发——Manifest V3、后台 Service Worker、扩展 API 与 Chrome 应用商店上架发布。不做扩展的人可以不装,省下常驻上下文。
更新节奏也要形成习惯。用官方安装器装的,跑一条 update 即可;插件方式装的,按各自助手的插件更新流程走(Claude Code 可以在插件菜单里给它开 AutoUpdate,再配合 /reload-plugins 重载)。为什么强调更新:指南内容跟着 Web 平台的发布列车走,特性从「易变」转「Baseline」、新指南上线,都要靠更新才能吃到。把它当成和升级浏览器同级别的例行动作就行。
内容家底:250 个特性、六大学科
它覆盖的是过去几年 Web 平台攒下的新特性,一共 250 个,按技术域分成三摞:
| 技术域 | 特性数 | 内容倾向 |
|---|---|---|
| CSS 与布局 | 140 | 布局系统、动画、色彩、滚动、排版 |
| HTML 与 DOM | 36 | 原生元素、弹窗、表单控件、DOM 行为 |
| JavaScript 与 API | 74 | 浏览器 API、调度、内置 AI、设备能力 |
按「学科」组织的六大核心方向,才是它真正的使用地图:
| 学科 | 解决什么 | 代表特性 |
|---|---|---|
| 用户体验 | 顺滑的视觉状态与转场 | View Transitions 视图过渡、滚动驱动动画、scrollbar-color |
| CSS 布局 | 现代布局与样式系统 | 容器查询、Subgrid 子网格、oklch 现代色彩空间、text-wrap 排版调优 |
| 性能 | 让页面快且稳 | 推测预加载、INP 诊断、scheduler.yield 任务调度 |
| 表单与 UI | 原生组件替代 JS 模拟 | Popover API、锚点定位(Anchor Positioning)、<dialog>、:user-invalid 校验、字段自动尺寸 |
| 无障碍 | 屏幕阅读器与键盘可达 | 焦点管理、内容导航与可发现性、原生语义 |
| 浏览器内置 AI | 端侧本地模型能力 | 本地翻译 API、摘要 API、语言检测 API |
对照这张表就能看出它的取向:它教的不是「新语法」,而是「这件事现在应该用平台的哪个原生能力做」——弹窗用 Popover 而不是 div 模拟,提示气泡用锚点定位而不是 JS 算坐标,长任务用 scheduler.yield 切分而不是硬扛主线程。每一个特性都是一次「把 JS 轮子还给浏览器」的机会。
WARNING六大学科里「浏览器内置 AI」这块要特别留神:本地翻译、摘要这类端侧 API 目前仍属较新的能力,浏览器支持面有限。指南会标注它们的成熟度,但千万别不看兼容状态就把实验性 API 写进生产主流程,具体怎么安全采用,看后面「安全采用」一节。
六大学科逐个深挖:每科都在治一种老毛病
上面那张表是地图,这一节逐科走一遍。每科的老毛病都一样:模型不是不知道新方案,而是默认先伸手去拿旧的那套。下面每个对照都是指南里真实存在的条目(括号里是对应的指南 ID,装好后可以 retrieve 出来看全文)。
用户体验:动画交给合成器,别再手写编排
老毛病:页面切换、元素进出场全靠 JS 手动编排——加类名、监听 transitionend、算 FLIP 位移,代码又长又容易抖。现代平台的做法是把动画声明出来、交给浏览器合成器跑:
// 老写法:手动记录元素位置、算位移、逐帧推动画// (FLIP 四步:First / Last / Invert / Play,几十行起步)
// 现代写法:状态切换包进 View Transitions,浏览器自动做形变过渡document.startViewTransition(() => renderNewState());滚动相关的效果同理。以前做阅读进度条要监听 scroll 事件再 requestAnimationFrame 节流计算,现在滚动驱动动画(指南 scroll-progress-indicator)直接把动画进度绑到滚动位置上,一行监听都不用写。弹窗、抽屉这类进出 top layer 的元素进出场动画,有专门的指南 animate-to-from-top-layer(下一节会把它整条拆开讲)。还有一条容易被忽略的:所有动效都要尊重 prefers-reduced-motion——指南 motion 专门讲怎么让动画留在合成器上跑、同时给晕动症用户留好降级。
CSS 布局:组件应该看自己的宽度,不是看屏幕的宽度
老毛病最典型:一个卡片组件,在侧边栏里要窄版、在主栏里要宽版,于是媒体查询断点越堆越多,组件和页面布局死死耦合。容器查询(指南 size-aware-styling、responsive-design)把判断依据从视口换成组件自己的容器宽度,组件从此自适应、可复用:
/* 老写法:断点跟着屏幕走,组件搬个位置就要改样式 */@media (max-width: 900px) { .card { flex-direction: column; } }@media (max-width: 600px) { .card { font-size: 14px; } }
/* 现代写法:组件只关心自己有多宽 */.card-wrap { container-type: inline-size; }@container (min-width: 420px) { .card { flex-direction: row; }}同科的其它「还轮子」动作还有:用 subgrid 让嵌套网格的子项直接对齐父网格的轨道,省掉一层层手算;用 oklch 和相对颜色语法从一个品牌色推导整套色阶,而不是手工调十几个十六进制值;标题排版用 text-wrap: balance 让浏览器自动均衡断行,告别手写 <br>;给手风琴、展开卡片做高度动画,以前要 JS 测高,现在 interpolate-size: allow-keywords 让 height: auto 也能过渡(指南 animate-to-intrinsic-sizes)。还有 :has()(指南 style-parent-with-has)让「根据子元素状态给父元素上样式」这种以前必须 JS 的活儿回归纯 CSS。
性能:先量出来,再对症下药
这一科的特点是「诊断指南」和「处方指南」成对出现。先说诊断:页面点了没反应、INP(Interaction to Next Paint)难看,先用指南 identify-inp-causes 定位是哪段 JS、哪次布局重算在拖后腿,再对着处方改:
// 老写法:一个大循环同步跑完,主线程冻住,用户点什么都没反应for (const item of hugeList) { process(item); }
// 现代写法:切分长任务,定期把主线程还给浏览器(指南 break-up-long-tasks)for (const item of hugeList) { process(item); if (needsToYield()) await scheduler.yield();}资源加载侧的老毛病是「一视同仁」:所有图片都懒加载,结果首屏大图(LCP)也被拖慢;或者所有资源都高优先级,互相抢带宽。指南 optimize-image-priority 的口径很明确:LCP 候选图给 fetchpriority="high",屏外图片和视频才 loading="lazy"(指南 lazy-load-video-and-audio)。再往前一步,下一页还没点就先备好:推测规则(Speculation Rules,指南 improve-next-page-load-performance)可以声明式地预取甚至预渲染用户大概率要去的页面,点击时近乎瞬开——而且它属于「增强型」特性,老浏览器直接忽略,零风险。长列表、信息流页面则用 content-visibility: auto(指南 defer-rendering-heavy-content)跳过屏外内容的渲染。埋点上报也有专门指南(batch-analytics-events、full-session-analytics):攒批、延后到用户离开时用 fetchLater() 一次发走,别让每个事件都去抢网络。
表单与 UI:原生组件早就长大了
这是「JS 轮子」重灾区。下拉层、气泡提示、日历选择器,前端们用 div 模拟了二十年,定位、点击外部关闭、Esc 关闭、焦点管理,每样都要手写,每样都容易漏。平台现在的原生答案是成套的:
<!-- 老写法:一个 div + 一大坨 JS(开关状态、外部点击监听、Esc 处理、焦点回收) --><div class="dropdown" id="menu">...</div>
<!-- 现代写法:Popover 属性 + 一个按钮,开关/关闭/层级全是浏览器管 --><button popovertarget="menu">菜单</button><div id="menu" popover>...</div>气泡提示的定位同理:以前 JS 测算坐标、监听滚动重定位、处理边缘翻转,现在锚点定位(Anchor Positioning)把提示元素在 CSS 里「锚」到触发元素上,翻转交给浏览器。表单校验的老毛病是时机不对——页面一打开就一片红,或者用 :invalid 在用户还没输入时就报错;现代口径是 :user-invalid:只在用户交互过之后才标错(指南 validate-input-after-interaction、required-field-feedback),和屏幕阅读器的报错播报还要同步(这条归无障碍科,指南 accessible-error-announcement)。文本框高度以前靠 JS 实时测 scrollHeight,现在 field-sizing: content 一行搞定(指南 form-fields-automatically-fit-contents)。登录、支付、地址这些高频表单,指南直接给了带正确 autocomplete 属性的完整范式(autofill-sign-in-form、autofill-payment-form、autofill-address-form)——自动填充对上了,用户少打一半字。连短信验证码都有专门指南(sms-otp-form,用 WebOTP 自动提取验证码)。还有个中文用户特别容易踩的坑:输入法组字时按回车被误提交——指南 ime-safe-enter-submit 专门讲这个。
无障碍:不是加分项,是原生语义的副产品
这一科和前面几科是连体的:用原生 <dialog>、Popover、原生表单控件,键盘可达、焦点管理、读屏语义大半是白送的;用 div 模拟,每一样都要自己补,还经常补错。指南里这一科条目不多但都很要害:
- 报错要让读屏用户在对的时机听到。视觉上用
:user-invalid在交互后标红,程序状态上同步aria-invalid,两边对齐,读屏用户才不会一进页面就被报错淹没(指南accessible-error-announcement)。 - CSS 生成内容别坑读屏。
::before/::after塞的图标字体、装饰字符会被某些读屏软件读出来,指南accessible-generated-content讲怎么给生成内容配替代文本或正确隐藏。 - 尊重系统文字缩放。全站字号用 px 写死,等于无视用户在系统里调大的字体;用 rem 并尊重操作系统的文字缩放偏好(指南
respect-os-text-scale),低视力用户才能正常用。 - 自定义组件别裸奔。真要造自定义元素,用 ElementInternals 的 ARIA 反射和
delegatesFocus把语义和焦点处理做对(指南accessible-web-components),而不是东拼西凑几个role了事。
浏览器内置 AI:能端侧跑的,别都往云上送
最新也最需要冷静看的一科。Chrome 正在把端侧模型能力做成 Web API:语言检测(指南 language-detection)、翻译(指南 translator)、摘要(指南 summarizer),还有更通用的 Prompt API(指南 language-model,支持流式输出、结构化 JSON 响应和多轮会话管理)。老写法是这类需求一律调云端 API——按量付费、数据出境、离线即残废;端侧 API 能跑通的场景(评论区语言识别、文章一键摘要、多语言站点的即时翻译),本地零成本、零延迟、数据不出设备。
但这一科的指南同时也是「安全采用」策略的重点关照对象:这些 API 大多还新,支持面以 Chrome 为主,指南会如实标注成熟度,正确姿势是把它们当增强——有就用、没有就回退到云端或干脆不提供这个功能,而不是把主流程押在上面。
它怎么工作:本地搜索、按需取指南、评测剪枝
装好之后,日常使用你其实感知不到它——流程是助手在后台自己跑的:
- 激活:你给助手派了个 Web 相关的活,它判断任务相关,激活
modern-web-guidance技能,并被指示用它的 CLI 查平台问题。 - 本地语义搜索:助手执行
modern-web-guidance search "<查询>"。搜索跑在本机,靠一个离线、零依赖的嵌入模型加 BM25 检索引擎匹配最相关的指南——全程不联网、不需要 API Key,npm 包自包含、无额外依赖,延迟低,供应链面也小。 - 取指南进上下文:助手再用
retrieve <指南 ID>把命中的指南拉进上下文窗口——里面是成段的目标代码范式、已知的坑和兜底写法,助手照着这个写,而不是照着训练数据的老习惯写。
有两个设计细节值得单独说:
第一是指南按 Token 效率裁剪。 指南不是把 MDN 整页塞进来。维护方跑评测来识别「模型本来就已经会」的内容并剪掉,只保留模型真正缺的那部分经验密度。上下文窗口寸土寸金,喂得准比喂得多重要。
第二是有效性有评测背书,不是自我感觉。 他们搭了完整的评测闭环:拿真实 Web 应用当考场,给出不点名任何 API 的真实需求(比如「让我的图片加载更快」),用 Playwright 检查器验证产出是否真的用了对的现代方案,再对比同一助手开/关技能的通过率。近期快照里,几个主流助手在两百多个任务上的通过率普遍从 50% 多提升到 80%–90% 多,也就是二三十个百分点的实打实提升。指南哪里没帮上忙,评测会暴露出来,内容随之迭代——这也是它敢说「经验密度」的底气。
一条指南的全程拆解:从搜到用,是什么样
抽象流程讲多了没感觉,拿官方快速开始里用的那条指南走一遍全程:给对话框的背景遮罩做进出场动画。
第一步,搜。 你(或者你的助手)想做的是「dialog 打开时遮罩淡入、关闭时淡出」,搜的是任务描述,不是 API 名:
npx modern-web-guidance@latest search "animate a dialog modal backdrop"命中的指南里有一条 animate-to-from-top-layer——专门讲怎么给 dialog、popover、tooltip 这类进出「顶层」(top layer)的元素做进场/退场动画。
第二步,取。 把指南全文拉进上下文:
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"指南的结构大致是四段:目标范式(推荐的目标代码长什么样)、为什么这样写(平台机制:元素进 top layer 前是 display: none,普通 transition 根本没机会触发)、坑点(退场动画最容易翻车的地方)、兜底(不支持的浏览器怎么优雅降级)。
第三步,看代码怎么变。 这个需求的老写法之所以难看,是因为要靠 JS 手动续命:关闭时先加一个 .closing 类播退场动画,setTimeout 等动画播完再真正关掉,还要防用户连点。指南给的现代范式把这些全收进 CSS:
/* 现代范式:进场起点、离散属性过渡,一次交代清楚 */dialog { transition: opacity 0.25s ease-out, transform 0.25s ease-out, overlay 0.25s allow-discrete, display 0.25s allow-discrete;}dialog::backdrop { transition: opacity 0.25s ease-out, overlay 0.25s allow-discrete, display 0.25s allow-discrete;}/* @starting-style 定义元素「第一帧」的样子,进场动画才有起点 */@starting-style { dialog[open] { opacity: 0; transform: translateY(10px); } dialog[open]::backdrop { opacity: 0; }}三个关键点,全是模型凭训练数据最容易漏的:一是 @starting-style 提供进场动画的起始帧,没有它元素只会「啪」地出现、只有退场动画;二是 display 和 overlay 这类离散属性要显式写进 transition 并标 allow-discrete,退场时元素才能留在 top layer 里把动画播完,而不是瞬间消失;三是遮罩 ::backdrop 要单独写它自己的过渡。这正是「知道 API 存在」和「会写生产级代码」之间的那层密度——也是这个技能包存在的全部理由。助手拿到这份指南后写出的代码,和它凭记忆写的,会是肉眼可见的两种东西。
评测体系:它凭什么说自己「有用」
技能包最容易沦为玄学:装上一堆指南,感觉代码变好了,但谁也拿不出证据。Modern Web Guidance 的做法是把这件事做成一条可重复的流水线,值得单独讲,因为这也是它和社区里各种「提示词合集」的根本区别。
考场是真实应用,考题不点名 API。 评测用的底座是两个真实风格的 Web 应用(代号 daily-grind、devtools-times),任务是模拟真实开发者的口吻提需求——比如「让我的图片加载更快」——故意不出现任何 API 或特性名。这一条很关键:它考的是助手能不能自己「发现」该用推测预加载、该调图片优先级,而不是听见关键词才想起来。
判卷是自动化的断言检查。 产出代码交给 Playwright 检查器,从四个层面验:源码里有没有用对模式、计算样式对不对、运行时 DOM 行为对不对、无障碍状态对不对。不是让另一个模型来「感觉一下好不好」,是硬断言。
尺子先要校准。 这是整套体系里最见功力的一环:同一套检查器,先跑专家写的黄金解(golden solutions,由 Claude、Codex、Antigravity 多家的解法校准),必须 100% 通过;再跑未改动的原始应用,必须 100% 不通过。两个极端都对上了,才证明检查器既不漏判也不误判,量出来的数才可信。
最后才是对比实验。 让编程助手在开/关技能两种模式下跑同一批任务,看通过率差。官方给两个指标:机会(opportunity)=100% − 裸奔通过率,是理论上能提升的空间;提升(uplift)=开启后 − 裸奔的通过率差,是实际吃到的部分。近期快照(200 多个任务、1700 多条断言)的数据长这样:
| 助手 + 模型 | 任务 / 断言数 | 裸奔 → 开启技能(提升) |
|---|---|---|
| Antigravity CLI(Gemini 4 Argon) | 214 / 1673 | 58% → 94%(+36pp) |
| Claude Code(Opus 5.5) | 215 / 1801 | 57% → 88%(+31pp) |
| Codex CLI(GPT-6.1 Sol) | 215 / 1795 | 54% → 82%(+28pp) |
读这张表要抓两个要点:第一,裸奔通过率都在 50% 多——不是模型不行,是「现代写法」这件事裸奔状态下本来就只有一半胜率,这正是机会所在;第二,提升幅度稳定在 30 个百分点上下,跨三家助手、三种模型都成立,说明涨的是指南的功,不是某个模型的脾气。完整的分助手、分指南明细在官方的 Eval Dashboard 上公开可查。
评测还反过来决定指南的存废。 闭环的最后一环:某个任务裸奔通过率已经很高,说明模型本来就会,对应指南就是在浪费 token,剪掉;某个任务裸奔老翻车、开了技能涨得最多,说明这条指南正中要害,保留并继续打磨。前面说的「指南按 token 效率裁剪」,靠的就是这套数据,而不是编辑的主观取舍。
安全采用:新特性不是无脑上
「多用新特性」如果理解成「哪里新用哪里」,迟早在老浏览器和边缘场景上翻车。这个技能包专门有一套安全采用策略,这也是它和普通「新特性安利文」拉开差距的地方:
- 分清增强与关键行为。纯增益型的特性(比如推测预加载)老浏览器静默忽略即可,不需要兜底;而对话框控件、网络信标这类关键行为,必须写经过认真考虑的低开销兜底。
- 兜底要轻。优先几十行以内的定制小兜底(官方口径是小于 50 行),或按需条件加载的 polyfill,拒绝为了一个小特性拖进一整个重型第三方包——那等于把省下的 JS 又加倍还回去。
- 兼容数据跟着 Baseline 走。指南接入 Baseline 项目的实时兼容数据,助手能按当前浏览器支持情况动态决定写法,而不是背某一年份的兼容表。
- 坑点写在明处。指南会记录平台的隐藏限制,比如
fetchLater()有 64KB 的载荷配额、macOS 特有的滚动条行为等——这些正是模型最容易凭感觉写错的地方。 - 实验性特性要过闸。Origin Trial 实验 API 和「易变特性」(单引擎刚发布三个月内、还在稳定期的特性)的指南可以被搜到,但
retrieve取全文时默认上锁,必须开发者显式同意才放行,防止助手自作主张把不稳定 API 用进项目。
把上面几条落成一张对照表会更清楚:
| 类型 | 例子 | 老浏览器上的表现 | 兜底要求 |
|---|---|---|---|
| 增强型特性 | 推测预加载、content-visibility、滚动驱动动画 | 静默忽略,页面照常工作 | 不需要兜底,直接用 |
| 关键行为特性 | 对话框控件、网络信标(fetchLater())、表单校验 | 功能缺失或行为错误 | 必须写低开销兜底,或特性检测后条件降级 |
助手用 Baseline 数据的方式也值得说清:指南不是写死「某年某月起可用」,而是接入 Baseline 项目的实时兼容状态——某个特性刚进入 Baseline 广泛可用(Baseline Widely available)时,指南的口径会随之从「谨慎尝鲜」变成「放心默认」。你在项目里要做的,是把自己的支持目标告诉助手(比如「要照顾两年前的 Safari」),它会按这个目标在「直接用 / 特性检测 / 上兜底」之间选。
至于实验特性为什么只锁 retrieve 不锁 search:这是个很克制的设计。锁搜索,等于让助手对这些能力一无所知,你问它「有没有办法做 X」它只会说没有;只锁全文,则助手知道有这么个东西、会主动向你说明「这是实验 API,需要你先开闸」,决策权回到人手里。单引擎发布三个月内的特性,API 形状还可能变——真金白银的项目代码,不该在不知情的情况下押上去。
放行开关通过项目根目录的 .mwgrc 配置文件控制,可以提交进仓库让全队共享:
# 允许助手取用 Origin Trial 实验 API 的指南npx modern-web-guidance@latest set-allow-origin-trials
# 允许助手取用易变特性的指南npx modern-web-guidance@latest set-allow-volatile-features这两条命令分别往 .mwgrc 里写入 "allowOriginTrials": true 和 "allowVolatileFeatures": true。用户级还可以放一份 ~/.mwgrc 作为全局兜底。默认两个都关——这是对的默认值:先让助手在全线可用的特性里把活干漂亮,真需要尝鲜时再由人来开闸。
.mwgrc 详解:一个文件,统一全队的闸门
上一节的两条 set-allow-* 命令,落点都是项目根目录的 .mwgrc——一个 JSON 文件,内容就这么直白:
{ "allowOriginTrials": true, "allowVolatileFeatures": false}两个键分工明确:allowOriginTrials 管 Origin Trial 实验 API 的指南全文(对应命令 set-allow-origin-trials),allowVolatileFeatures 管单引擎新发布、还在稳定期的易变特性(对应命令 set-allow-volatile-features)。查找顺序是:先看项目根目录的 .mwgrc,没有再看用户级的 ~/.mwgrc 兜底。所以个人尝鲜可以放用户级,团队口径放项目级——项目级的存在会盖过个人设置,这正是想要的:进了这个仓库,所有人的助手都按同一套闸门行事。
团队里用它,建议走三条规矩:第一,文件提交进仓库,和代码一起评审,开闸关闸都是一次可见的变更,而不是某个人在自己机器上悄悄改的;第二,默认全关,需要哪个开哪个,PR 里写明为什么要用这个实验特性、兜底在哪;第三,开了闸的特性要记一笔账——它们进入 Baseline 或正式发布后,把闸关回去、把当时的临时兜底清掉,别让「临时」变成「永久」。
WARNING
.mwgrc是全队生效的开关,不是个人偏好。给团队项目开实验闸之前先过评审:一个人尝鲜,全队的助手都会开始往代码里写实验 API。
legacy-scan 实战:给老代码库做一次现代化体检
新项目靠指南「写对」,老项目靠的是先「查清」。legacy-scan 就是那个体检入口:
npx modern-web-guidance@latest legacy-scan .它扫的是「遗留模式」——那些平台已经有原生替代、但代码还在用老写法实现的地方。报告怎么读、按什么顺序动手,建议照下面这套流程走:
第一步,先按学科归拢,别按文件归拢。 扫描结果天然会聚成几类:弹窗类(div 模拟的 dialog/popover)、布局类(媒体查询断点堆叠、手写网格兜底)、性能类(同步长任务、全量渲染、图片优先级缺失)、表单类(自制校验、JS 测高)。同类问题用同一条指南批量解决,比逐个文件零敲碎打效率高得多。
第二步,按风险分三档排顺序:
第一档,增强型(风险几乎为零):预加载缺失、content-visibility、图片 fetchpriority 这类——老浏览器自动忽略,直接改,改完抽查即可。
第二档,组件替换型(风险中等):div 弹窗换 Popover/<dialog>、JS 定位换锚点定位、断点堆叠换容器查询——涉及交互与样式回归,逐个组件改,配视觉与交互回归测试。
第三档,关键行为型(风险高):表单校验逻辑、数据上报信标——改错了影响业务正确性,按「安全采用」的兜底要求逐项来,改一项验一项。
第三步,每改一项,retrieve 一条指南。 扫描负责告诉你「哪里老」,指南负责告诉你「新写法长什么样、坑在哪」。比如扫出一个手写下拉层,先 retrieve Popover 相关的指南再动手,而不是让助手凭记忆重写——凭记忆正是老毛病的来源。
第四步,改完跑一遍回归再继续。 优先级最高的回归是交互路径(弹窗开关、表单提交)和无障碍状态(焦点、读屏播报),这两样恰好也是评测体系里 Playwright 检查器重点验的层面,可以借鉴同样的检查清单。
WARNINGlegacy-scan 给的是「可以现代化」的清单,不是「必须全改」的工单。十年老项目一次性全仓替换,等于把回归风险攒成一颗雷:按档位分批改、分批上线,每批都留好回滚余地。
适合谁
- 天天用 AI 写前端的人。如果你已经在用编程助手写页面(参见本系列的 AI 编程助手实战),这个技能包是性价比极高的一层「品味校准」:模型不变、流程不变,只是它写出来的代码从「能跑的老派实现」变成「现代平台实现」。通过命令行使用助手的(参见 命令行里的 AI 助手)同样适用,它对各家 CLI 助手都有对应的装法。
- 想把老项目往现代平台迁的人。先用
legacy-scan对代码库做一次遗留模式盘点,再按指南逐项替换——哪些 div 弹窗可以换 Popover、哪些手写布局可以换容器查询,路径是现成的。 - 对包体积和性能敏感的项目。它的整个导向就是「能用原生就不用库」,长期下来砍掉的是实打实的 JS 体积和维护面。
反过来,如果你的项目压根不碰浏览器前端,或者技术栈被锁定在很老的浏览器环境(新特性大面积用不上),它的收益就有限——指南再好,落地不了也是白搭。
常见问题与排障
装完之后,助手写代码还是老样子,技能没生效?
先确认安装向导识别对了你的助手、技能文件落到了正确目录;插件方式安装的,装完通常要重载插件或新开一个会话。也可以手动验证 CLI 本身是通的:在项目目录跑一次 npx modern-web-guidance@latest search "popover",能返回指南列表,说明工具侧没问题,剩下的就是助手侧的激活配置。
search 搜不到我想要的指南?
换查询的表述方式再试:它匹配的是「你想做的事」,用描述任务的自然语言(比如 “animate a dialog modal backdrop”)通常比只敲一个 API 名效果好。也可能这个特性属于被上锁的实验/易变类别——能搜到标题却取不出全文时,先看是不是需要 .mwgrc 放行。
retrieve 提示指南被锁定(gated)?
这是有意设计:Origin Trial 与易变特性的全文默认上锁。确认你真的要尝鲜后,在项目根目录执行对应的 set-allow-* 命令生成 .mwgrc,再重新取。团队项目里这个文件应该提交进仓库,让所有人的助手行为一致。
指南里的写法和我们项目的浏览器支持目标冲突? 指南接入的是 Baseline 实时兼容数据,面向的是当前主流支持面。如果你的项目还要照顾更老的浏览器,按「安全采用」一节的思路处理:关键行为补轻量兜底,或者干脆不用该特性——技能给的是建议,最终拍板的兼容策略在你手里。不要反过来把兜底写成主实现、新特性当摆设,那就本末倒置了。
它会把我的代码或提示词传出去吗? 搜索与取指南全在本地跑,离线可用。但要注意:Google 会收集匿名使用信息(安装数、调用的助手名、被取用的指南 ID、助手生成的搜索查询词),不收集原始用户提示词。在意的可以在 Shell 配置里关掉:
export DISABLE_TELEMETRY=1内容会不会过时?
这正是它用 npx ...@latest 分发的原因:每次拉的都是最新指南。用安装器装的跑一次 update 即可;插件方式装的按对应助手的插件更新流程走。Web 平台半年一变,装完就不管、一年不更新,指南的价值会肉眼可见地缩水。
它和直接查 MDN 有什么区别? MDN 是给人看的参考手册,信息全但密度平;这里的指南是给模型看的「纠偏材料」:只保留模型不知道或容易用错的部分,附带生产级范式、坑点和兜底,并且经过评测验证真的能改变模型产出。人查手册、助手吃指南,分工不同。
指南的写法和我们项目现有的规范、组件库冲突,听谁的? 听你项目的。指南给的是「平台层面的最佳实践」,不是强制标准:你们已经有成熟的弹窗组件、设计系统,就没必要为了用 Popover 把组件库推倒。正确用法是把指南当评审意见——它指出「这里平台有原生能力」,采纳不采纳由项目规范拍板。长期看,更值钱的动作是把「我们项目决定不用 X、因为 Y」这类结论沉淀下来,下次评审直接引用,而不是每次和助手重新争一遍。
团队里每个人装的版本不一样,助手行为对不齐怎么办?
先统一安装方式:要么全员用官方安装向导,要么全员用同一个插件市场,别混着来。然后把两件事固定下来:一是 .mwgrc 提交进仓库,闸门口径全队一致(见前面 .mwgrc 一节);二是把「定期跑一次 update」写进团队的入职清单或迭代例行事项。版本差异的麻烦不在功能多少,而在同一个任务不同人跑出两种风格的代码,评审成本全耗在这种地方。
离线或内网环境能用吗?
用的时候完全可以:搜索和取指南都是本地跑的,零依赖、不联网、不需要 API Key,断网不影响助手查指南。需要联网的只有「获取」环节——第一次安装、后续更新要拉 npm 包。所以内网环境的标准做法是:在有网的机器上装好、更新好,再把环境同步进去;日常开发全程离线无碍。遥测按前面说的用 DISABLE_TELEMETRY=1 关掉即可。
两个技能包都要装吗?
看你做什么。只做普通网站,主包 modern-web-guidance 就够了;只有当你还要开发 Chrome 扩展时,才需要再加 chrome-extensions 包(Manifest V3、Service Worker、扩展 API、上架发布那一套)。两个包的技能描述加起来也就几百 tokens,常驻成本不高,但没用到的包不装,是对上下文窗口的基本尊重。用 --choose 在安装时挑好即可,后来想加随时能补装。
小结
Modern Web Guidance 补的是 AI 编程助手最隐蔽的一块短板:不是不会写代码,而是写的代码停留在训练数据的平均年代。它的做法很务实——浏览器厂商和 MDN 的专家把 250 个现代特性的正确用法、兼容状态和兜底策略,裁剪成模型缺的那部分经验密度,通过本地 CLI 按需喂进上下文;再用评测闭环持续验证「喂了真的有用」,用 .mwgrc 闸门守住实验性特性的边界。
谁最值得装,排个序:第一是每天靠 AI 写前端、且对产出质量有要求的人——你省下的不是打字时间,是逐行纠正老派写法的评审时间;第二是手里有老项目要长期维护的人——legacy-scan 加逐条指南,是把「现代化」从口号拆成可执行工单的最短路径;第三是团队的技术负责人——与其在代码评审里一遍遍口头传达「我们这儿弹窗用原生、布局用容器查询」,不如把厂商指南加 .mwgrc 闸门变成助手默认遵守的基础设施,规范落在工具里,比落在文档里管用。
它和上一篇的 Skill Seekers 搭配起来,正好是一套组合:Modern Web Guidance 是「厂商出的成品」——平台的最佳实践不用你操心,装上就生效;Skill Seekers 是「自家作坊」——把你们项目的组件库文档、内部规范、业务手册炼成私有技能,补上厂商指南不可能覆盖的那部分。一个管「平台的规矩」,一个管「我们项目的规矩」,两层都齐了,助手才既写得现代、又写得像你们团队的代码。
如果你只记一件事:与其换更强的模型,不如先给现在的助手补上它缺的那层平台经验——这个技能包就是目前这条路上最权威、最省事的一份现成答案。