必须在构建阶段注入关键css，因html与css版本需对齐，手动维护易过期且无法适配多变体；vite用rollup-plugin-critical、webpack用critical cli生成并内联，同时须同步处理csp哈希与缓存策略。
不能直接在 HTML 中用 <style></style> 标签硬塞关键 CSS，除非你明确控制构建时的资源注入时机和顺序；否则会破坏 CSP、绕过缓存、丢失媒体查询条件判断，甚至导致 FOUC 或样式错乱。
为什么 inline 关键 CSS 必须在构建阶段完成
关键 CSS（Critical CSS）指首屏渲染必需的样式规则。它必须在 中同步加载，不能依赖外部 <link rel="stylesheet">。但手动维护容易过期，且无法适配不同视口或主题变体。
常见错误现象包括：
- 上线后首屏白屏时间变长（关键 CSS 没生效）
- 内联样式被 CSP
style-src 'self'拦截（未配置'unsafe-inline'或 hash） - 构建后 CSS 文件路径变化，但 HTML 中的内联内容没更新，样式失效
根本原因：HTML 是静态模板，CSS 是构建产物；二者版本必须对齐，而对齐动作只能发生在构建时。
Vite 项目中用 rollup-plugin-critical 注入关键 CSS
该插件会在构建阶段分析 HTML 模板 + CSS 产物，提取匹配首屏选择器的规则并内联。它比纯 PostCSS 方案更可靠，因能真实模拟浏览器渲染路径。
实操建议：
- 安装：
pnpm add -D rollup-plugin-critical - 在
vite.config.js的build.rollupOptions.plugins中添加：
import critical from 'rollup-plugin-critical';
export default defineConfig({
build: {
rollupOptions: {
plugins: [
critical({
base: './dist',
src: '/index.html',
dest: '/index.html',
inline: true,
extract: false,
penthouse: { blockJSRequests: false, timeout: 30000 }
})
]
}
}
});
注意点：
-
base必须与vite.config.js中的build.outDir一致，否则找不到 CSS 文件 -
penthouse的timeout建议设为 30s，CI 环境中 Puppeteer 启动慢 - 若页面含动态 class（如
class="btn btn--${theme}"），需在penthouse配置中显式传入cssString或预编译变量
Webpack + html-webpack-plugin 下用 critical CLI 提前生成
Webpack 生态中不推荐用插件实时注入，因为 html-webpack-plugin 渲染时机早于 CSS 提取插件（如 mini-css-extract-plugin）完成，容易读到空 CSS。
更稳妥的做法是：在 build 脚本后加一步 CLI 提取，再用 html-webpack-plugin 的 templateParameters 注入结果：
- 先执行构建：
webpack --mode=production - 再运行：
critical ./dist/index.html --base ./dist --inline --dimensions '{"width":1920,"height":1080}' > ./dist/critical.css - 最后用自定义模板读取
critical.css内容并插入<style></style>
关键风险点：
-
criticalCLI 默认使用 Headless Chrome，CI 环境需确保已安装 Chromium（GitHub Actions 可用actions/setup-chrome@v1） - 若 HTML 使用了服务端模板语法（如
{{title}}），critical会报解析错误，需先用html-minifier-terser清理或跳过注释 - 多语言或多主题站点，必须为每个
index.[lang].html单独运行critical，不能复用同一份输出
内联后必须同步处理 CSP 和缓存策略
内联样式会触发 CSP 的 style-src 检查，也会影响浏览器对 HTML 文件的缓存判断——哪怕只改了一行 CSS，整个 HTML 都得重新下载。
必须做的两件事：
- 在构建后生成 style hash，写入 CSP HTTP 头或
<meta http-equiv="Content-Security-Policy">，例如：style-src 'self' 'sha256-abc123...' - 禁用 HTML 的长期缓存：
Cache-Control: no-cache, must-revalidate，避免用户看到旧内联样式 + 新 JS 导致布局错乱
最容易被忽略的是：当团队启用 Link: ; rel=preload 时，内联关键 CSS 后仍保留该 header，会造成重复加载——必须在构建脚本中检测是否已内联，再决定是否输出 preload header。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
