导语 | 这篇教程能帮你给 AI 编码助手装上 260 多项现代 Web 规范,让它少写 jQuery 式的过时代码。适合用 Claude Code、Copilot CLI、Antigravity 写前端的人,不用碰构建工具。从试跑到接入,第一次大约 15 分钟。

让 AI 写个弹窗,它给你塞一个 jQuery 插件;让它做个吸顶导航,它写一堆滚动监听。你明明只想快点把页面做出来,结果还要花时间给 AI 擦屁股。
这不是你提示词写得不好。Google Chrome 团队把这个毛病说得很直白:编码智能体之所以总默认用老套路,是因为它们训练时见过太多旧代码,浏览器早就自己能做的事,它们还在引重库。2026 年 11 月,Chrome、Edge、Firefox、MDN 四个团队联合开源了一个东西,专门治这个病,叫 Modern Web Guidance。它在这次 GitHub 日榜上冲到过第一,source 仓库单日涨了约 1230 颗星(数据截止 11 月 15 日,来源见文末)。
这篇教程就带你把它从零装进自己的编码工作流。不用装插件市场里的东西也能先试,试完再决定要不要正式接入。
01 | 开始之前:准备与环境
先把门槛说清楚,省得走到一半才发现缺东西。
工具本体:Modern Web Guidance(官方中文叫「现代 Web 指南」),本质是一个命令行工具加一组给 AI 用的技能包,npm 包名是 modern-web-guidance。代码用 Apache 2.0 协议、指南内容用 CC-BY 4.0 协议,开源免费(协议信息来自二级信源引用官方 README,官方页面本身未单独标注收费)。
环境要求:需要 Node.js 22 或更高版本,这是官方 README 写死的门槛。有些媒体报道说 Node 24 也能跑,那是作者的实测机器,不代表最低要求,按 22 来准备最稳。
一个编码助手:要真正发挥价值,你得有个 AI 编码工具,官方明确给了接入方式的有 Claude Code、Copilot CLI、Antigravity,以及任何支持 npx skills 的工具。只想先试试手感的,没有编码助手也能跑。
预计耗时:三条命令试跑 5 分钟,正式接入 10 分钟,给老项目做体检的时间看代码量。
注意:官方博客地址容易找错,正确的文档入口是developer.chrome.com/docs/modern-web-guidance,不是带/blog/的路径。后文所有命令都以官方文档和官方仓库 README 为准。
02 | 第一步:不安装,先用三条命令试手感
做什么:用 npx 直接调用,不写任何配置文件,先确认这东西能在你机器上跑起来。
怎么做:打开终端,依次试这三条。第一条按关键词搜指南,第二条按 ID 取一份完整指南,第三条扫描当前目录里的老代码。
# 搜索相关指南
npx modern-web-guidance@latest search "animate a dialog modal backdrop"
# 按 ID 取出一份指南
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"
# 扫描代码库里的过时写法
npx modern-web-guidance@latest legacy-scan .前两条实测几秒内返回。搜「弹窗背景动画」会给你一份指南 ID 列表,比如 animate-to-from-top-layer、light-dismiss-a-dialog;取出后你会看到它讲 @starting-style、transition-behavior: allow-discrete、overlay 这些现代 CSS 属性。
为什么:官方把它设计成一个「智能体按需调用」的小工具,检索走的是本地向量索引加 BM25 匹配,官方 README 明确写着不发起网络请求、不需要 API key。所以你能离线跑通,先试再装,试错成本几乎为零。
避坑提示:如果 npx 报错说 Node 版本太低,先去 nodejs.org 装 22 以上再回来。别急着装 24,先看自己项目对 Node 版本的兼容性。03 | 第二步:选对接入方式,把它装进你的编码助手
做什么:试完觉得有用,就正式安装,让它常驻在你的编码工具里。
怎么做:最省事的是官方推荐的交互式向导,跑起来会一步步问你装到哪。
npx modern-web-guidance@latest install如果你用的是具体编码工具,官方给了更直接的入口,按需选一条:
# 通用:Vercel Agent Skills 方式
npx skills add GoogleChrome/modern-web-guidance
# Claude Code
claude plugin marketplace add GoogleChrome/modern-web-guidance
claude plugin install modern-web-guidance@googlechrome
# Copilot CLI(在对话框里输入)
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
# Antigravity CLI
agy plugin install https://github.com/GoogleChrome/modern-web-guidance以后要更新,跑 npx modern-web-guidance@latest update 就行。
为什么:这些命令看着多,其实是同一个技能包接进不同工具的入口。选对入口的意义在于能持续收到更新,技能包本身只有约 205 tokens(主包),塞进上下文几乎不占地方。
避坑提示:Claude Code 用户特别注意,从内置的claude-plugins-official市场装会卡在 v0.0.194 这个旧版本拿不到更新,要走上面写的googlechrome市场。二级信源实测时踩过这个坑。
04 | 第三步:给老项目做一次代码体检
做什么:把 legacy-scan 指向你的项目目录,让它找出现代化改造机会。
怎么做:在项目根目录跑第一条命令;想把本地检查和智能体审核结合起来做迁移,接第二条。
npx modern-web-guidance@latest legacy-scan .
# 结合本地语法检查与上下文智能体审核,迁移旧模式
npx modern-web-guidance@latest legacy-scan官方把这个功能描述成「快速本地语法检查」加「上下文智能体审核」的组合,目标是迁走旧写法。
为什么:装技能包解决的是「AI 别再写老代码」,扫描老项目解决的是「已经写下的老代码怎么办」。两个方向加一起,新代码旧代码才都能顾到。
避坑提示:扫描只覆盖部分模式。二级信源在小测试目录上看到 CLI 自称只覆盖 33 条指南、约占全部的 20%。所以「0 findings」不等于你的代码已经现代化,别拿它当合格证。
05 | 第四步:调好两个开关,用得更踏实
做什么:关掉默认遥测,搞清楚实验性特性为什么取不出来。
怎么做:不想让 Google 收集匿名使用数据的话,装之前设一个环境变量。官方页面和二级信源都提到,遥测默认开启,收集的是智能体名称、指南 ID 和搜索词,不含你的原始提示词。
export DISABLE_TELEMETRY=1碰到某个指南 search 能搜到、retrieve 却取不出来的情况,通常是它属于 Origin Trial 或单引擎不稳定的特性。官方的设计是这类指南故意在取用环节上锁,要在仓库里建 .mwgrc 文件显式开启,防止智能体在你没同意的情况下用上不稳定 API。
为什么:这两个开关一个管隐私、一个管稳定。默认设置是给多数人准备的,你按自己的场景调完,用起来才不会被动。
避坑提示:它只负责「指导」,不保证结果。官方自己的评估里,开了引导仍有部分检查没通过。涉及兼容性时一定在真实浏览器里验一遍,尤其是用户里还有老安卓机的情况。
关键信息卡
| 步骤 | 关键操作 | 备注 |
|---|---|---|
| 准备 | 装 Node.js 22+,备好 Claude Code 等编码助手 | 开源免费,Apache 2.0 / CC-BY 4.0 |
| 试跑 | npx modern-web-guidance@latest search / retrieve / legacy-scan | 免安装、离线、无需 API key |
| 接入 | install 向导,或按工具选 marketplace 命令 | Claude Code 走 googlechrome 市场 |
| 体检 | legacy-scan . | 仅覆盖约 20% 模式,0 发现不等于合格 |
| 调优 | DISABLE_TELEMETRY=1、.mwgrc | 遥测默认开,实验特性默认锁 |
常见问题
问:它和直接问 AI「用现代写法」有什么区别?
区别在于指南是专家审过、带浏览器兼容性数据的。官方口径是覆盖 262 项现代 Web 特性(CSS 与布局 140、HTML 与 DOM 37、JavaScript 与 API 85)和 204 个真实开发用例,数据来自官方 README。你在提示词里喊一句「用现代写法」,AI 未必知道现在该用 @starting-style 还是老写法,这个工具把答案直接塞进它的上下文。
问:官方说通过率多少?可信吗?
官方 Chrome 文档写的是开启引导后通过率 91%,无引导的前沿模型约 51%。二级信源引用的 11 月 8 日快照则是 Claude Code 从 57% 升到 88%、Codex CLI 从 54% 升到 82%、Antigravity CLI 从 58% 升到 94%,约 215 个任务。两组数字来自不同时间点和不同口径,都是项目方自己公布的,当参考看就好,别当成承诺。
问:我 Node 是 20,能用吗?
不行。官方 README 明确要求 Node.js 22 或更高。升级 Node 之前看下你其他项目的兼容情况,别为了这个工具把老项目搞崩。
问:支持哪些编码助手?
官方文档明确列了 Vercel Agent Skills、Claude Code、Copilot CLI、Antigravity。Codex 的接入方式官方页面没写,但二级信源的评估数据里出现了 Codex CLI,说明至少有测试覆盖,想用可以先按通用 npx skills 方式试。
写在最后
这个工具最打动我的地方,不是它涨了多少星,而是它把「浏览器已经能做的事就别再引库」这件事,做成了一条条能塞进 AI 上下文的具体指南。AI 写代码越来越快,但快不等于对,给喂进去的规范做一次升级,投入十分钟,省的是后面每一次返工。
不过也别神化它。它只是把合格线画清楚,真正落地还得你在浏览器里点一遍、测一遍。
照着做下来,你卡在哪一步了?是 Node 版本没过、retrieve 取不出指南,还是扫描结果和你预期对不上?评论区说说,我挑典型问题单独拆。
信息来源
- Chrome for Developers 官方文档《Modern Web Guidance》(官方一级信源,定义、安装与接入命令、200+ 技能、91% 通过率、遥测说明的依据;已验证 HTTP 200)
- GoogleChrome/modern-web-guidance-src 官方源码仓库(官方一级信源,README 中 262 项特性、204 用例、Node 22+ 要求、search/retrieve/legacy-scan/install 命令的依据;已验证 HTTP 200)
- GoogleChrome/modern-web-guidance 官方发布仓库(官方一级信源,技能包发布入口;已验证 HTTP 200)
- npm 包 modern-web-guidance(官方包,v1.0.1 与 npx 调用命令;npmjs 页面对脚本返回 403,浏览器可访问,同一包元数据经 https://registry.npmjs.org/modern-web-guidance 验证 HTTP 200)
- CrazyCodersLab:Modern Web Guidance 实测(二级媒体实测,2026-11-15,star 数据、eval 分组数据、遥测与 legacy-scan 覆盖限制的来源;已验证 HTTP 200)
- DEV Community:GitHub 热门开源工具盘点(二级社区,2026-11-16 GitHub Trending 快照佐证;已验证 HTTP 200)
数据检索截止时间:2026-11-21 14:12(北京时间)。热度与 star 数据为 11 月 15 至 16 日快照,属「热度参考,非实时数据」。