critters提取的关键css没生效的根本原因是html模板未被正确识别为可处理入口，它仅作用于html-webpack-plugin注入的普通外部标签，不处理内联、js动态插入或preload链接。
为什么 Critters 提取的关键 CSS 有时没生效？
根本原因通常是 HTML 模板未被 Critters 正确识别为“可处理入口”——它只作用于通过 html-webpack-plugin 注入的 <link rel="stylesheet"> 标签，且要求这些样式表是普通外部文件（非 style 标签内联、非 JS 动态插入）。如果项目用的是 vite-plugin-html 或直接写死 <style></style> 块，Critters 默认完全不介入。
实操建议：
- 确认构建流程中使用了
html-webpack-plugin（Webpack 场景），且其template是 .html 文件（不是 .ejs/.pug 等需额外 loader 解析的格式） - 所有待提取的 CSS 必须以
<link href="xxx.css" rel="stylesheet">形式出现在模板中，不能是<link href="xxx.css" rel="preload" as="style">，也不能是import './index.css'后由 CSS 插件注入的 link - 若用 Webpack 5+，确保
css-minimizer-webpack-plugin在Critters之后运行，否则压缩可能提前移除关键样式
Critters 的 inlineFonts 和 prerender 该怎么选？
这两个选项控制不同阶段的行为：inlineFonts 决定是否将 @font-face 规则内联进关键 CSS；prerender 决定是否在构建时模拟浏览器渲染以计算“首屏关键样式”。后者开销大、不稳定，多数场景应关掉。
实操建议：
- 设
inlineFonts: true可避免 FOIT（字体闪烁），尤其适合自托管字体。但注意：若字体文件路径含 hash（如fonts/inter-abc123.woff2），需确保Critters能解析出真实路径——它默认只处理相对路径或 public 目录下的资源 -
prerender: false是安全默认值。开启后需额外配puppeteer，且对 JS 渲染依赖强的页面（如 Vue/React 需挂载后才出 DOM）极易提取失败，返回空 CSS - 真正需要
prerender的场景极少，仅限纯静态 HTML + 复杂媒体查询 + 无 JS 干预的布局，比如文档站首页
提取后关键 CSS 体积异常大，怎么调 include 和 exclude？
Critters 默认提取所有匹配选择器的样式，包括第三方库（如 node_modules 中的 normalize.css）和未使用的工具类（如 mt-4）。不加约束会导致内联 CSS 膨胀，反而拖慢首屏。
实操建议：
- 用
include限定范围，例如include: [/src\/styles\/critical\.css$/]，强制只处理明确标记为关键的文件 - 用
exclude屏蔽干扰项，例如exclude: [/node_modules/, /_debug/, /\.print\.css$/] - 避免用宽泛正则如
/\.css$/—— 它会把所有 CSS 都塞进关键块，失去“关键”意义 - 检查提取结果：构建后打开生成的 HTML，搜索
<style data-critters></style>标签，人工核对是否含明显非首屏样式（如#admin-panel、.modal-hidden）
Webpack 5 下 Critters 报错 Cannot read property 'tapAsync' of undefined
这是插件与 Webpack 编译生命周期钩子不兼容的典型错误，本质是 Critters 版本太老，仍尝试调用 Webpack 4 的 compilation.plugin API，而 Webpack 5 已废弃该写法。
实操建议：
- 升级到
@critters/webpack-plugin@0.2.0+（注意命名空间已变，旧版critters-webpack-plugin已归档） - 确认安装命令是
npm install -D @critters/webpack-plugin，而非旧包名 - 若用 TypeScript，需额外装
@types/critters（非必须但避免类型报错） - 删除
node_modules和package-lock.json后重装，避免残留旧版本插件被误引用
真正麻烦的不是配置本身，而是它依赖整个构建链路的“干净度”：HTML 模板路径、CSS 引入方式、Webpack 版本、甚至 html-webpack-plugin 的实例数量（多实例需分别传参）。任何一环松动，关键 CSS 就可能静默失效，而你只看到首屏闪一下白屏。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
