掃描類別名稱

#概覽

讓靜態建置取得類別名稱，同時避免將變動值變成新的類別。撰寫完整的候選類別、以 CSS 變數處理連續值，並且只在輸入超出整合的一般範圍時調整來源探索。原生 CSS 的移除另有傳遞流程。

#在原始碼中保留完整類別

掃描器讀取原始碼文字，不會執行應用程式。元件需要選擇狀態色時，請將每個類別完整寫出：

const className = error ? 'bg-red-60' : 'bg-green-60'

靜態擷取無法從 'bg-' + tone 這類片段取得完整結果。多種狀態會選擇不同類別時，請使用有限的對照表：

const statusClasses = { error: 'bg-red-60', success: 'bg-green-60' }const className = statusClasses[status]

掃描器不必執行這次查找，就能找到兩個候選類別。執行階段與漸進式渲染可為首次在瀏覽器得知的有效 utility 名稱生成規則；原始碼中的完整字串是靜態掃描的要求，不代表禁止動態 utility。選擇方式請參閱渲染模式。

原生類別使用情況也會供修剪使用，即使該類別不是 Master CSS utility。

文字說明

1. 探索. 透過整合預設方式或明確的來源指令尋找應用程式原始檔。
2. 擷取. 讀取完整候選字串，不執行應用程式碼。
3. 解析. 使用目前啟用的 manifest，為辨識出的 Master CSS 類別生成規則。

即使同時只使用其中一個分支，兩個分支仍都能被掃描器看到。各類別生成的內容取決於目前啟用的專案定義：

@layer theme {  :root,  :host {    --color-green-60: oklch(67.52% .2298 142.5);    --color-red-60: oklch(60.94% .2501 29.2)  }}@layer utilities {  .bg-green-60 {    background-color: var(--color-green-60)  }  .bg-red-60 {    background-color: var(--color-red-60)  }}

兩個分支是來源中的選項，不是依序執行的步驟。擷取不會預測選中的分支，也不會憑空推導串接後的 class 名稱。

文字說明

1. error ? "bg-red-60" : "bg-green-60" 讓擷取能看見兩個完整的靜態 class 字串。
2. "bg-" + tone 不會提供完整的結果 class。掃描器不會推論 tone 的值。
3. 選項有限時請使用完整候選字串；值本身不受限時，則使用固定 class 搭配動態 CSS 變數。

#不要將變動值放進類別名稱

假設標題大小來自編輯器控制項。請保留完整類別，並修改元素上的自訂屬性：

<h1 id="headline" class="(font-size:var(--headline-size))" style="--headline-size: 2rem">  Launch notes</h1>

document.getElementById('headline').style.setProperty('--headline-size', '3rem')

@layer utilities {  .\(font-size\:var\(--headline-size\)\) {    font-size: var(--headline-size)  }}

完成靜態建置後，在瀏覽器主控台執行這段 JavaScript。標題會變大，但不會加入類別或生成新規則。區域自訂屬性不需要註冊 @theme，也不需要 Master CSS 執行階段。如果類別名稱本身是在啟動後才首次出現，請使用執行階段或漸進式渲染。

瀏覽器解析更新後的自訂屬性。靜態樣式表中已包含完整規則。

文字說明

相同 font-size 類別出現在兩個標題上方。將 --headline-size 從 2rem 改為 3rem，會讓第二個標題變大，不必引入其他類別。

#納入一般探索範圍之外的來源

先使用整合或 CLI 的一般來源探索。共用元件目錄若在其範圍之外，再於負責掃描的樣式表中明確加入來源。路徑以該樣式表為相對基準：

@import '@master/css';@source "../shared/**/*.tsx";@source not "../shared/**/*.test.tsx";

此範例納入同層的 shared/ 目錄，並排除其測試。比對模式應只涵蓋必要輸入。@source 提供類別候選，不會匯入樣式表，也不決定階層串接優先順序。不要只因缺少一個元件，就加入整個儲存庫。

外部內容提供的 utility 名稱若是有限集合，請列出完整候選：

@safelist "bg-red-60" "bg-green-60";

安全清單讓這些候選可供生成，不會將類別加入元素，也不會讓無效名稱變成有效。無上限的值應使用變數，不要嘗試逐一列舉。@blocklist 會排除候選；找到類別卻仍未生成 CSS 時，請檢查這項政策。

先檢查來源有無納入，再檢查類別政策。圖解不表示類別字串會當作 JavaScript 求值。

文字說明

原始檔先提供完整類別候選，再由獨立政策關卡決定是否保留；缺少來源，就無法提供其中的類別。

路徑模式、候選篩選與其優先順序請參閱掃描指令。請區分原始檔從未被讀取，以及候選被政策移除這兩種情況。

#找出樣式缺漏的原因

1. 使用類別檢查工具，依目前啟用的專案 manifest 檢查完整類別。
2. 確認原始檔有納入掃描。一般應用程式檔案使用整合或 CLI 的預設探索；只有明確例外才加入 @source。
3. 檢查候選政策。@source not 可排除檔案，@blocklist 可移除類別。已知且有限的外部類別集合可使用 @safelist。
4. 規則已生成時，確認此頁已載入所屬樣式表。已載入時，先檢查選擇器是否符合，以及勝出的階層串接宣告，再調整來源探索。
5. 缺少的是原生規則時，請依原生修剪檢查處理，包含外部類別與稍後出現的狀態。執行階段 utility 生成無法重建任意被移除的原生選擇器。

來源邊界、候選掃描與驗證請參閱擷取。

#接著處理原生 CSS 傳遞

#修剪未使用的原生 CSS

原生 CSS 預設保留。若要移除未使用的原生類別規則，請依照只修剪已知的使用集合。該流程先確立傳遞的負責範圍，再說明檔案明確啟用、套件邊界、保留狀態與關鍵影格相依關係。

#保留廠商樣式表

類別由外部提供時，可選擇有限的安全清單，或保留擁有這些原生規則的檔案。保護外部與不確定的來源包含範例與政策限制。

#驗證輸出

原始碼中存在指令，不代表整合已提供使用集合。獨立驗證修剪步驟提供可重現的 CLI 檢查，並說明該檢查能證明什麼。