给 AI 编码助手装上现代 Web 规范:Modern Web Guidance 从零上手教程

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

Modern Web Guidance 让 AI 把过时代码改写成现代 Web 布局的概念示意图

让 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 取不出指南,还是扫描结果和你预期对不上?评论区说说,我挑典型问题单独拆。


信息来源

  1. Chrome for Developers 官方文档《Modern Web Guidance》(官方一级信源,定义、安装与接入命令、200+ 技能、91% 通过率、遥测说明的依据;已验证 HTTP 200)
  2. GoogleChrome/modern-web-guidance-src 官方源码仓库(官方一级信源,README 中 262 项特性、204 用例、Node 22+ 要求、search/retrieve/legacy-scan/install 命令的依据;已验证 HTTP 200)
  3. GoogleChrome/modern-web-guidance 官方发布仓库(官方一级信源,技能包发布入口;已验证 HTTP 200)
  4. npm 包 modern-web-guidance(官方包,v1.0.1 与 npx 调用命令;npmjs 页面对脚本返回 403,浏览器可访问,同一包元数据经 https://registry.npmjs.org/modern-web-guidance 验证 HTTP 200)
  5. CrazyCodersLab:Modern Web Guidance 实测(二级媒体实测,2026-11-15,star 数据、eval 分组数据、遥测与 legacy-scan 覆盖限制的来源;已验证 HTTP 200)
  6. DEV Community:GitHub 热门开源工具盘点(二级社区,2026-11-16 GitHub Trending 快照佐证;已验证 HTTP 200)

数据检索截止时间:2026-11-21 14:12(北京时间)。热度与 star 数据为 11 月 15 至 16 日快照,属「热度参考,非实时数据」。

本文来自投稿,不代表本站立场,如若转载,请注明出处:
-- 展开阅读全文 --
AutoClip:贴一个链接,把两小时访谈剪成 10 条能直接发的竖版短片
« 上一篇 11-21