共计 7184 个字符,预计需要花费 18 分钟才能阅读完成。
先扫到的不是弹窗,是输入法选字时的那个回车
npm 包 1.0.0 · Linux 实测 · 不必先装技能
我在本地写了一份很小的留言页,文本框里加了一句很常见的逻辑:按回车就提交,Shift+回车才换行。然后用 Modern Web Guidance 的 legacy-scan 扫了一遍目录。它先标出来的,不是我写的遮罩层弹窗,而是这件事——中文输入法还在选字时,这个回车也会把内容发出去。
扫描器给这条命中起的名字叫 ime-safe-enter-submit,并写明要先看 event.isComposing,再补上 event.keyCode === 229。下面这条命令在 0.715 秒里给出了完整结果:
npx modern-web-guidance@latest legacy-scan ./pageChrome 在 2026 年 11 月 10 日把 Modern Web Guidance 发到了稳定版 1.0,Firefox 与 Edge 加入共同维护。GitHub 上 v1.0.0 的发布说明写明:这套工具带 203 篇用例指南,覆盖 250 个网页平台特性。我没把技能装进某个编码代理,只在 Linux 测试机上用 npm 包 1.0.0 跑了 search、retrieve 和 legacy-scan。下面按实际敲过的命令写。

▲ 示意图:先扫自己的页面,再对照官方指南看现代写法。水彩示意,不代表真实界面。
· · ·
PART 01
它是什么,要解决什么问题
按 Chrome 官方文档 的定义,Modern Web Guidance 是一套技能,用来把网页平台的经验、常见写法和浏览器兼容数据,直接交给编码代理用。它针对的问题是:模型的训练数据里有大量旧代码,代理常常用一大段 JavaScript 去实现浏览器现在已经能原生做的事。
2026 年 11 月 10 日的官方博客 宣布 1.0 稳定版,并写明 Firefox 与 Edge 加入共同维护,项目同时有 MDN 团队参与。GitHub 上有两个容易混在一起的仓库,星数不能加在一块看:
- 产品仓 GoogleChrome/modern-web-guidance:用来安装的技能包和 CLI。我在 2026-11-12 14:59(北京时间)用 GitHub API 读到 5430 颗星。
- 源码仓 GoogleChrome/modern-web-guidance-src:开发用的源仓库,当天也出现在 GitHub Trending 日榜。同一时刻 API 读数为 1999 颗星。
命令行可以先试用,不必先把技能装进 Claude Code 或 Cursor。官方 README 给出的三条是:search 按需求搜指南,retrieve 按编号取回全文,legacy-scan 在本地扫旧写法。

▲ 产品仓 Release v1.0.0 页面,拍摄于 2026-11-12(北京时间)。发布说明写明 203 篇用例指南、覆盖 250 个平台特性;发布时间按 GitHub 记录是 2026-11-10 11:24:59(北京时间)。
legacy-scan 是 1.0 里比较适合在测试机上亲手跑的部分。现代化工作流文档 写明:它用 AST、DOM 和 CSS 解析器在本地扫描 HTML、CSS、JavaScript/TypeScript、部分框架组件和 package.json,zero LLM calls or token cost,也就是不调用大模型、不产生 token 费用。规则在大约 45,000 个开源仓库上测试过;默认上线的规则,静态匹配精度至少 80%,复核后精度至少 90%。发布说明还写了,它目前只覆盖其中约 20% 能做确定性检测的指南。
🍎 官方在 2026 年 11 月 11 日的另一篇博客里写过:在他们的评估集上,未加引导的编码代理平均大约通过 50% 的检查,使用 Modern Web Guidance 后大约 90%。这是官方评估集上的对比,不能理解成你自己的项目也会从 50 提到 90。原文在 Top 10 things AI gets wrong in web development。
Paul Irish 在 Hacker News 发过一条 Show HN。我在 2026-11-12 约 15:00(北京时间)打开时,页面显示 429 分、142 条评论。讨论里还有不少关于浏览器支持范围的意见,本文只确认这条讨论存在,不把帖子里的数字当作官方计数。
· · ·
PART 02
用前准备
要在本地跑这三条命令,需要这些条件:
- 已安装 Node.js,并能访问 npm。我用的是 v24.22.1。
- 不必先执行
install。search、retrieve、legacy-scan都可以直接用npx跑。 - 第一次执行时,
npx会下载 npm 包modern-web-guidance。我读到的最新版本是 1.0.0,发布时间为 2026-11-10 11:29:19(北京时间)。随后用npx modern-web-guidance@latest --version复核,输出就是1.0.0。
我实际使用的命令都加了 -y,避免 npx 中途询问是否安装包,并设置了 DISABLE_TELEMETRY=1。这是官方 Show HN 帖里示范过的写法,不是扫描本身的必选项。
为了让扫描结果看得出差别,我自己写了一份体积很小的留言演示页,没有搬别人的项目。页面里故意放了这些旧写法:用 scrollHeight 让文本框跟着输入长高;回车直接提交且不做输入法判断;一打开就给 :invalid 输入框画红框;手风琴用 max-height: 9999px 做展开动画;再从 jsDelivr 引入 jQuery,且不加 Subresource Integrity。另外还写了自定义遮罩层弹窗,以及跟着鼠标走的提示条,这两处后面会单独说明。

▲ 本机打开的演示页,拍摄于 2026-11-12(北京时间)。必填框还没输入,就已经套上了 :invalid 的红色样式。这正是后面一条命中要讨论的问题。
· · ·
PART 03
先 search,再 retrieve
官方 README 的试用例子是搜「给对话框的背景做动画」。我按原文跑了:
npx modern-web-guidance@latest search "animate a dialog modal backdrop"2026-11-12 15:01:15(北京时间)这次调用耗时 0.415 秒,返回 10 条指南,第一条就是 animate-to-from-top-layer,说明是给对话框、弹出层和提示条做进入、离开顶层时的动画。后面还能看到点击外部关闭对话框、打开模态框时锁住页面滚动、以及不用 JavaScript 声明式控制对话框等条目。
接着按这条 ID 取回全文:
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"这次耗时 0.315 秒,终端里直接打出指南正文,包括实现步骤、示例和回退策略。v1.0.0 发布说明写过:search 现在用无额外依赖的嵌入模型加 BM25,而且完全离线。我这次是在已经下载过 npm 包的机器上跑的,没有再断网验证离线这一点,正文只转述发布说明。
search 按需求找编号 → retrieve 取回指南正文 → 自己看实现步骤和浏览器支持
🍎 search 和 retrieve 解决的是「我想做某件事,现代写法是哪一篇」。legacy-scan 则是反过来:对着已经写好的代码,看能确定检测出来的旧模式。两套命令可以分开用,不必先装技能。

▲ Chrome for Developers 文档「Modern Web Guidance」首页,拍摄于 2026-11-12(北京时间)。来源:https://developer.chrome.com/docs/modern-web-guidance
· · ·
PART 04
对这份演示页跑 legacy-scan
命令和官方文档里写的一样,路径指向演示页目录:
npx modern-web-guidance@latest legacy-scan ./page2026-11-12 15:01:15(北京时间)这次调用耗时 0.715 秒,退出码 0。开头几行是:
Modern Web Guidance Analyzer — ./page
Found 5 modernization opportunities across 5 guides (scanned 33 guides with deterministic rules; ~20% of the guidance corpus):
Note: Static analysis results are provisional — verify against the Keep/Drop criteria below.也就是:扫到 5 个现代化机会,对应 5 篇指南;这一次实际启用了 33 篇带确定性规则的指南,大约相当于整个指南库的 20%。加 --json 再跑一次(0.665 秒),机器可读结果里写的是 totalFindings: 5,activeGuideCount: 33,activeRuleCount: 35。这两次扫描的命中条目一致。
5 条命中是:
animate-to-intrinsic-sizes:styles.css第 43 行,手风琴用max-height过渡来模拟内容高度动画form-fields-automatically-fit-contents:app.js第 16 行,用scrollHeight改文本框高度ime-safe-enter-submit:app.js第 22 行,回车提交时没检查输入法合成态secure-external-subresources:index.html第 9 行,CDN 上的 jQuery 脚本没有integrityvalidate-input-after-interaction:styles.css第 29 行,用:invalid给还没交互过的输入框上色
我故意写的自定义遮罩层弹窗,以及跟着鼠标走的提示条,这一次没有被标出来。这不等于那两处已经是现代写法。官方也说了,扫描器只覆盖大约 20% 能做确定性检测的指南;没标到,可能是规则还没收录,也可能是我的写法没对上匹配条件。
现代化工作流文档还写明:现在没有 --fix 开关。看起来像「改一行 CSS」的替换,经常会变成跨 HTML、CSS 和脚本的改动,还要考虑浏览器支持。扫描结果是一份待复核清单,不是自动改代码。

▲ 本机终端输出原文,命令于 2026-11-12 15:01:15(北京时间)执行,耗时 0.715 秒,包版本 1.0.0。截图由真实日志渲染,未改写命中内容。

▲ 演示页源码摘录,拍摄于 2026-11-12(北京时间)。位置与扫描结果中的文件名、行号一致。
· · ·
PART 05
把 5 条命中对照官方指南拆开
扫描器给每条命中都附了 Keep when / Drop when。官方的意思是:先看周围代码,确认这不是有意保留的回退,也不是长得像、其实不该改的写法,再决定动不动手。我按扫描给出的编号,一次取回了这 5 篇指南:
npx modern-web-guidance@latest retrieve animate-to-intrinsic-sizes,form-fields-automatically-fit-contents,ime-safe-enter-submit,secure-external-subresources,validate-input-after-interaction这次耗时 0.365 秒。下面按我页面里的实际代码,对照指南里的现代写法和回退说明。我没有在这篇里把演示页改完再复扫,只把「扫到了什么」和「指南怎么说」拆开。
回车提交会碰到中文输入法
我在文本框上监听 keydown,只要按下 Enter 且没有按 Shift,就直接 requestSubmit()。扫描器指出:这样会在 CJK 输入法合成过程中误触发提交。
指南 ime-safe-enter-submit 的写法是:在提交前检查 event.isComposing;同时建议加上 event.keyCode === 229。指南解释过,部分浏览器在输入法选字时仍可能把 event.key 报成 Enter,但 keyCode 会是 229。它也写了,KeyboardEvent.isComposing 目前属于有限可用,所以这个 229 判断不是多余的兼容代码,而是指南推荐的回退。
对在中文环境写网页的人,这条最值得先看。我自己就是带着这个习惯写的演示页,一扫就被抓住了。
用 scrollHeight 让文本框长高
我在 input 事件里把高度设成 textarea.scrollHeight。指南 form-fields-automatically-fit-contents 给出的现代写法是 CSS:field-sizing: content,并建议同时设置最小和最大尺寸,避免输入框被撑破,也避免缩成一条缝。指南注明:field-sizing 的 Baseline 状态是 Newly available,自 2026-06-16 起进入 Baseline;不支持时,控件会回到固定高度。若仍要在旧浏览器里自动长高,指南给的是先用 CSS.supports('field-sizing', 'content') 判断,不支持再挂原来的脚本。
手风琴用 max-height: 9999px 做动画
演示页的展开面板默认 max-height: 0,加上 open 类后变成 9999px,再用 CSS 过渡。指南 animate-to-intrinsic-sizes 把这种写法视为用超大 max-height 去模拟「高度跟着内容走」。它给出的现代属性是 interpolate-size: allow-keywords,以及需要做计算时使用 calc-size(),让 height 或 block-size 可以直接过渡到 auto 这类关键字。
这两项目前都是有限可用。指南写得很明确:它们属于渐进增强,不支持的浏览器会直接跳到目标尺寸,而不是平滑过渡;用 calc-size() 时还要另写一条普通的关键字回退。扫描建议里也提到,需要跨浏览器时,可以保留 max-height 作为回退。所以这条命中不该理解成「删掉 max-height 就结束了」。
一打开就给必填框画红框
演示页用 #note-form input:invalid 和 textarea:invalid 上色。打开页面、还没输入,三个必填框就已经是红的。指南 validate-input-after-interaction 给出的是 :user-invalid:等用户改过并离开输入框,或点了提交,再显示错误。:user-valid / :user-invalid 的 Baseline 状态是 Widely available,自 2023-11-02 起进入 Baseline。指南另外写了,视觉状态不会自动同步到 aria-invalid,如果要给读屏用,还得自己写同步逻辑。
CDN 脚本缺少完整性校验
演示页从 jsDelivr 引入了 jQuery 3.7.1,标签上没有 integrity,也没有 crossorigin。指南 secure-external-subresources 要求给这类不可变的第三方脚本加上 Subresource Integrity,以及 crossorigin="anonymous",并建议加上 referrerpolicy="no-referrer"。哈希要按本地核对过的文件计算,不能随手编一个。我在这篇里没有去算这条脚本的哈希,只确认扫描器找到了这处缺失。

▲ 示意图:扫描命中要对照指南全文和浏览器支持说明,不能只看终端里的一行摘要。水彩示意,不代表真实界面。
· · ·
PART 06
若要接到编码代理上,官方写的步骤是这些
把技能装进某个代理,官方文档和博客给出的推荐命令是:
npx modern-web-guidance@latest install已经装过预览版的,则用 npx modern-web-guidance@latest update。文档里还列了其他入口,例如 npx skills add GoogleChrome/modern-web-guidance,以及 Claude Code、Copilot CLI、Antigravity 各自的插件安装命令。
我没有执行 install。--help 里能看到 install 是一条正式命令,但没有列出清楚的非交互参数;官方文档也把它写成向导式安装。这类向导可能会改本机或项目里的代理配置,我没有在测试机上继续点下去,所以不能写成「已经接到 Claude Code / Cursor 里验证过」。
现代化工作流文档把代理侧的用法写成四步:扫描(legacy-scan --json)→ 按 Keep/Drop 复核 → 向你汇报 → 在你要求现代化时,再 retrieve 对应指南并改代码,然后对改过的文件复扫。文档举例的自然语言是「Modernize this repository using Modern Web Guidance」这类整库请求;如果只点名某一个组件,它会走普通的指南查找,而不是整库扫描。文档也写了,自动化 CI/CD 接入仍在开发。
· · ·
适合谁
这份工具更适合已经在用编码代理写前端,或者手头有一批旧页面、想先做一轮本地检查的人。search 和 retrieve 也可以当手册来用,不一定要接进代理。legacy-scan 的好处是快、不调用大模型;限制同样清楚:它只覆盖约 20% 带确定性规则的指南,结果还要按 Keep/Drop 自己看一遍,也不会自动改代码。
如果你主要写的不是网页,或者代理很少碰 HTML/CSS,不必专门为它改工作流。若只是想看某一类现代写法,直接 search 再 retrieve 就够了。

▲ 示意图:先在本地跑扫描,再决定要不要把技能装进代理。水彩示意,不代表真实界面。
相关阅读:让 AI 自己开网页、点按钮:agent-browser 实测、Meta 开源的设计系统 Astryx 上手、Matt Pocock 的 skills 安装和使用教程。




