交互式 Vite 应用不一定需要在浏览器生成 CSS。按钮可以切换两个规则已存在于静态样式表中的 classes。真正有用的区别是完整 class 名称何时可取得,而不是界面是否会变化。
假设一个客户端渲染应用,源代码中有两种按钮色彩,构建后 HTML 只有空挂载点,而浏览器首次渲染显示一个按钮。这三种输入描述同一个应用,却会提供不同的 class 集合给 Master CSS。
本页内容
#同一个应用,三种输入
从已加载 CSS 入口的既有 Vite 设置开始。这个小型原生 JavaScript 示例将两种变体保留在源代码中,并用 JavaScript 创建按钮:
<div id="app"></div><script type="module" src="/src/main.js"></script>import './style.css'const tones = { blue: 'bg-blue', neutral: 'bg-neutral' }const button = document.createElement('button')let active = falsefunction update() { button.className = active ? tones.neutral : tones.blue button.textContent = active ? 'Selected' : 'Select'}button.addEventListener('click', () => { active = !active update()})update()document.getElementById('app').append(button)源代码包含 bg-blue 与 bg-neutral。HTML 文件两者皆无,因为 JavaScript 尚未创建按钮。浏览器执行入口模块后,已连接的按钮带有 bg-blue;点击后则改为 bg-neutral。
同一个应用,三种 class 集合
这是同一个客户端渲染应用可选择的不同生成输入。更改 class 可以复用既有静态 CSS;空 HTML 挂载点无法提供初始按钮规则。
文字说明
- 源代码 → 静态 CSS. 按钮源代码包含 bg-blue 与 bg-neutral,静态模式在选择任何状态前就会生成两个规则。
- 构建 HTML → 预渲染 CSS. 输出的 HTML 只有空应用挂载点,没有任何按钮 class,因此 pre-render 模式不会生成任何按钮规则。
- 已连接 DOM → runtime CSS. 浏览器首次渲染连接带有 bg-blue 的按钮,runtime 模式生成该规则;后续切换至 bg-neutral 时,也会生成其规则。
图解比较三种生成策略的输入,不是三个连续构建阶段,也不是建议同时运行三种模式。
#静态 CSS 也能覆盖会变化的界面
使用默认 masterCSS() 插件设置时,扫描器会在 src/main.js 找到两个完整字符串。即使按钮同时只带有一个 class,生成样式表仍包含两个规则。点击只是切换符合哪个既有规则,不会要求 Master CSS 生成 CSS。
这种方式适合尺寸选择、状态标签与导航选中等有限状态。映射表中应保留完整 class 字符串,改用 `bg-${tone}` 组合就会失去源代码证据:扫描器不会执行插值来找出可能结果。扫描与裁剪说明完整 class 工作流与显式源代码例外。
CSS 可用与应用渲染是两件事。此示例若禁用 JavaScript,静态样式表仍存在,按钮却不会出现,因为它由应用代码创建。Master CSS 静态模式不保证客户端渲染应用能在没有 JavaScript 时运行。
#空挂载点不是已渲染的页面
Vite 普通的生产构建以 index.html 为默认入口。Master CSS pre-render 模式处理构建输出的 HTML,不会执行应用入口,将挂载点变成按钮。
使用 masterCSS({ mode: 'pre-render' }) 时,此示例的 HTML 没有按钮 classes,因此两种按钮色彩都不会有生成规则。浏览器之后可以创建按钮,但 pre-render 模式不提供 Master CSS runtime 来生成缺少的规则。
pre-render 模式适合构建确实输出有内容 HTML 的情况。若该 HTML 已包含 <button class="bg-blue">Select</button>,Master CSS 就能据此生成蓝色 class 规则。neutral 变体若只在点击后出现,仍需要其他 CSS 来源。HTML 由框架生成时,请使用框架集成。
#浏览器生成跟踪已连接的 classes
使用 masterCSS({ mode: 'runtime' }) 时,runtime 观察已连接的按钮并生成蓝色规则。点击引入 neutral class 时,也会生成该规则。最后一个使用元素停止使用规则后,规则仍可能留在缓存中;跟踪已连接的使用情况不代表 CSS 会立刻移除。
这种方式可处理首次在浏览器出现的完整 class 名称,例如可视化编辑器输入;但生成样式也因此依赖 runtime 启动。对于上方的有限映射表,静态模式已能覆盖两种状态,不需要这项依赖。
#渐进式渲染适用的情况
渐进式模式将输出 HTML 的生成 CSS,与浏览器对后续 classes 的支持结合。它与 pre-render 模式有相同的 HTML 边界:空挂载点无法提供初始按钮规则。这种情况下,应用代码创建按钮后,浏览器仍须生成规则。
HTML 已覆盖初始界面,而额外 classes 确实会稍后出现时,这种组合才有价值。初始生成 CSS 会随文档抵达;页面 hydration manifest 让 runtime 在延后加载引擎时仍能跟踪已覆盖的 classes。manifest 外的 class 会启动引擎。渲染模式指南维护完整模式比较、hydration 行为与失败条件。
这个机制说明 CSS 何时可用,不代表已证明绘制时间改善或总下载量减少;这些结果取决于应用,需要实际测量。
#更改模式前,先验证输入
以生产模式构建示例,再比较输出 HTML 与实时 DOM。HTML 应仍是空挂载点;JavaScript 执行后,DOM 应出现按钮。静态模式下,检查链接的生成样式表是否同时包含 .bg-blue 与 .bg-neutral,再点击按钮确认两种状态都有样式。
评估 pre-render 或渐进式模式时,请在响应的 style#master-css 中寻找实际应用 classes 与规则。检查响应源代码,不要只看实时 DOM,因为浏览器生成可能掩盖初始覆盖不足。只观察开发行为,不能证明生产环境的传递方式。
源代码中可见的 classes 已能完成任务时,请保持静态模式。选择其他输入,应是因为它包含源代码无法提供的信息,再验证所选生命周期是否确实提供这些信息。安装方式仍集中于 Vite 指南,渲染契约则位于渲染模式。

