新功能2025年4月22日

搭配 Vite 使用 Master CSS：選擇 CSS 生成時機

從來源掃描、輸出的 HTML 與已連接 DOM 觀察同一個互動應用，理解為何介面變化不一定需要 runtime CSS。

作者

Aron

互動式 Vite 應用不一定需要在瀏覽器生成 CSS。按鈕可以切換兩個規則已存在於靜態樣式表的 classes。真正有用的區別是完整 class 名稱何時可取得，而不是介面是否會變化。

假設一個用戶端渲染應用，來源中有兩種按鈕色彩，建置後 HTML 只有空掛載點，而瀏覽器首次渲染顯示一個按鈕。這三種輸入描述同一個應用，卻會提供不同的 class 集合給 Master CSS。

本頁內容

#同一個應用，三種輸入

從已載入 CSS 入口的既有 Vite 設定開始。這個小型原生 JavaScript 範例將兩種變體保留在來源中，並用 JavaScript 建立按鈕：

index.html

<div id="app"></div><script type="module" src="/src/main.js"></script>

src/main.js

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。

圖解比較三種生成策略的輸入，不是三個連續建置階段，也不是建議同時執行三種模式。

#靜態 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 指南，渲染契約則位於渲染模式。