網站導覽
開始使用

安裝 Master CSS

選擇框架整合、確認 CDN 是否可用，或透過 CLI 產生樣式表。

本頁目錄

選擇適合專案的設定方式：整合將 Master CSS 接入框架或建置工具，CLI 則為沒有打包工具的專案產生樣式表。CDN 提供使用預設集的純 HTML 設定。

#整合

既有應用程式請使用整合。預設為靜態渲染：建置時會在原始碼尋找完整類別名稱，並將樣式表傳遞到瀏覽器。選擇你的框架以查看設定檔與步驟，或使用下方的自動安裝程式。

執行階段與伺服器渲染設定，請參閱各整合的渲染支援。

#開始之前

使用 Node.js 24，並開啟應用程式根目錄，也就是 package.json 所在的位置。安裝程式會更新既有專案，不會建立框架起始專案。你的應用程式應已具備可正常運作的開發指令。

#套件版本

安裝程式、整合與其他 Master CSS 套件，請使用本文件所示的版本。手動安裝或更新時，也請讓這些套件維持相同版本。其他 npm 標籤下已存在的套件，不代表與本設定相容。

若要在本地評估執行階段，請使用已建置原始碼的 CDN 範例。其中的指令碼、編譯後的程式與基礎樣式表必須來自同一次建置。

手動設定或框架專用檔案，請參閱整合指南。若專案沒有對應的建置整合，請依獨立 CLI 設定操作。

  1. #加入 Master CSS

    從專案根目錄執行安裝程式。它會偵測框架與套件管理工具、更新設定檔，並安裝與安裝程式版本相同的 Master CSS 套件。

    npm create @master/css@2.0.0 -- --yes
    檢視或限制設定內容

    --yes 會接受建議的預設值，包括核心整合、ESLint 設定、MCP 套件，以及 AGENTS.md 中的 Master CSS 指引。輸出的 MCP 註冊與 skill 安裝指令，是編碼工具可選的後續步驟；安裝程式不會執行它們。

    加入 --dry-run，即可在不變更專案檔案、不安裝預定相依套件的情況下，檢視計畫：

    npm create @master/css@2.0.0 -- --yes --dry-run

    若只要核心框架設定，請在安裝指令加入 --minimal。它會略過 ESLint、MCP 與代理程式指引的新增內容。若想自行安裝相依套件，請加入 --no-install。

  2. #檢查樣式表連接

    閱讀設定摘要，完成其中列出的框架專用步驟。有些整合需要後續設定指令，或獨立的 CSS 產生程序；請參閱你的框架指南。

    確認應用程式有載入安裝程式建立或更新的樣式表。該樣式表應包含：

    @import '@master/css';

    例如，純 Vite 應用程式通常從 src/main.js 匯入 ./style.css。CSS 檔名與匯入位置會依框架而異。只安裝套件，不會自動將樣式表載入頁面。

    連接原始碼與頁面

    整合會從原始碼讀取類別名稱，並從樣式表讀取定義。應用程式必須載入該樣式表，產生的 CSS 才能傳到頁面。

    文字說明
    1. 原始碼. p-md 這類完整類別會出現在整合掃描的原始檔中。應用程式樣式表匯入 @master/css，提供預設集定義。
    2. 建置整合. 兩份原始資料交給已設定的整合，為辨識出的類別產生 CSS。安裝程式負責設定這個連接；整合負責後續的開發與建置工作。
    3. 頁面. 應用程式載入樣式表，讓產生的 CSS 到達瀏覽器。使用預設集時，p-md 規則會套用 1rem 內距。單純安裝套件，並不會建立樣式表匯入。

  3. #開始使用 Master CSS

    使用應用程式原本的指令，例如 npm run dev，啟動或重新啟動開發伺服器。將以下標記放進可見的頁面或元件。JSX 中請以 className 取代 class。

    檢查第一個樣式

    <p class="w-fit mx-auto my(0) p-md r-md b(1) b-solid b-line-divider bg-surface-raised text-sm fg-text-strong">Hello World</p>
    產生的 CSS
    @layer theme {  :root,  :host {    --color-zinc-90: oklch(24.6% .0022 265);    --color-zinc-100: oklch(15% .0016 265)  }  :root,  :host {    --color-surface-raised: light-dark(var(--color-white), var(--color-zinc-90));    --color-line-divider: light-dark(oklch(0% 0 none / .12), oklch(100% 0 none / .12));    --color-text-strong: light-dark(var(--color-zinc-100), var(--color-white))  }  :root,  :host {    --color-white: oklch(100% 0 none)  }  :root,  :host {    --font-size-sm: .875rem;    --text-sm: var(--font-size-sm);    --text-sm--line-height: 1.5;    --text-sm--letter-spacing: 0;    --radius-md: .375rem;    --spacing-md: 1rem  }}@layer utilities {  .text-sm {    font-size: var(--text-sm);    line-height: var(--text-sm--line-height, normal);    letter-spacing: var(--text-sm--letter-spacing, normal)  }  .bg-surface-raised {    background-color: var(--color-surface-raised)  }  .b-line-divider {    border-color: var(--color-line-divider)  }  .r-md {    border-radius: var(--radius-md)  }  .b-solid {    border-style: solid  }  .b\(1\) {    border-width: calc(1 * 1px)  }  .fg-text-strong {    color: var(--color-text-strong)  }  .my\(0\) {    margin-block: calc(0 * 1px)  }  .mx-auto {    margin-inline: auto  }  .p-md {    padding: var(--spacing-md)  }  .w-fit {    width: fit-content  }}
    使用預設集時，p-md 會在文字四邊各加入 1rem 內距。

    你應看到文字位於帶邊框的小面板內。將 p-md 改成 p-lg 並儲存：四邊內距都應從 1rem 增加為 1.5rem。這不只是確認安裝程式成功完成，也驗證了原始碼變更確實傳到頁面。

透過一個小修改驗證完整流程

安裝成功只是第一步。修改類別能同時檢查類別探索、CSS 產生與樣式表傳遞。

文字說明

原始碼從 p-md 改成 p-lg，編譯後的內距跟著改變，瀏覽器中的方框明顯變大。

#CDN

CDN 安裝會直接在瀏覽器執行 Master CSS，不需要建置工具。它適合純 HTML 原型；產生的樣式依賴 JavaScript。若頁面必須在沒有 JavaScript 時仍有樣式，請使用整合或 CLI。

執行階段指令碼、編譯後的程式與預設集樣式表，必須使用相同的 Master CSS 版本。範本中的網址已採用相符的版本。整合與 CLI 也有相同的套件版本要求。

將這個範本儲存為 index.html：

index.html
<!DOCTYPE html><html lang="en" hidden><head>  <meta charset="utf-8">  <meta name="viewport" content="width=device-width, initial-scale=1">  <link rel="preload" as="style" href="https://cdn.master.co/css-preset@2.0.0/src/base.css">  <link rel="preload" as="script" href="https://cdn.master.co/css-runtime@2.0.0">  <link rel="preload" as="fetch" crossorigin href="https://cdn.jsdelivr.net/npm/@master/css-runtime@2.0.0/dist/default-program.bin">  <link rel="stylesheet" href="https://cdn.master.co/css-preset@2.0.0/src/base.css">  <script src="https://cdn.master.co/css-runtime@2.0.0"></script></head><body>  <h1 class="m-2xl italic font-5xl font-heavy fg-text-strong">Hello World</h1></body></html>

標題應有 3rem 外距、2.5rem 斜體字型、900 字重，以及預設集的強調文字色。將 font-5xl 改成 font-6xl：文字會增大至 3rem。執行階段也會觀察 JavaScript 造成的類別變更。

樣式表提供基礎規則與串接層順序。傳統指令碼會自動啟動、載入相符的編譯程式，並在文件解析完成後產生初始類別。規則準備好後，它會移除 hidden。三個預先載入連結會提早開始樣式表、指令碼與程式請求；二進位檔使用 as="fetch" crossorigin，因為執行階段擷取的是資料，不是模組。二進位檔預先載入與執行階段擷取會直接使用 jsDelivr 目的網址，因為 Master CDN 重新導向未附帶 CORS 標頭。CDN 設定使用預設集；自訂 @theme 或 @utility 定義請透過整合編譯。

試用本地建置

從已建置的原始碼工作目錄，將 packages/preset/src/base.css、packages/runtime/dist/global.min.js 與 packages/runtime/dist/default-program.bin 複製到 index.html 旁的同一個目錄。指令碼與程式必須來自同一次建置。

將兩個樣式表網址替換為 ./base.css、兩個指令碼網址替換為 ./global.min.js，並將程式預先載入網址替換為 ./default-program.bin。透過 HTTP 提供目錄並開啟 index.html。使用明確的指令碼檔案時，執行階段會在檔案旁解析程式；若使用 Master CDN 或 jsDelivr 的 npm 套件進入點，則會解析該套件內的 dist/default-program.bin。

hidden 為可選屬性，可避免首次繪製時出現無樣式內容；已處理的程式載入錯誤，以及執行階段三秒啟動逾時，都會顯示內容。若停用 JavaScript 或指令碼本身無法下載，就無法移除該屬性。若這些情況下內容仍必須可讀，請省略 hidden，或提供靜態 CSS。

若有內容安全政策，請允許 CDN 與其 jsDelivr 重新導向目標載入指令碼、樣式表及擷取程式（connect-src），並允許執行階段產生的樣式表。不會擷取 Wasm。載入與 hydration 行為請參閱執行階段渲染。

#CLI

不加入打包工具，也能從 HTML 產生靜態樣式表。CLI 會掃描完整類別名稱並寫入 CSS，再透過一般樣式表連結載入。專案沒有對應的框架整合時，請使用此設定。

  1. #安裝 Master CSS

    將 Master CSS CLI 安裝為開發相依套件。

    npm install -D @master/css-cli@2.0.0

  2. #建立 CSS 進入點

    建立匯入預設 Master CSS 進入點的樣式表。

    main.css
    @import "@master/css";

  3. #執行建置指令

    執行指令掃描原始碼，並寫入 master.css。

    npx @master/css-cli generate "index.html" --output master.css --watch

  4. #載入產生的樣式表

    將下方文件儲存為 index.html。監看程序會依其中的類別名稱產生 master.css。提供此目錄並開啟頁面，即可看到已套用樣式的段落。

    檢查已安裝的樣式

    index.html
    <!DOCTYPE html><html lang="en"><head>  <meta charset="utf-8">  <meta name="viewport" content="width=device-width, initial-scale=1">  <link rel="stylesheet" href="./master.css"> </head><body>  <p id="master-check" class="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">Hello World</p></body></html>
    中性色表面、細邊框、小圓角，以及四邊各 1rem 的內距。

#建置以部署

監看指令會持續執行，並在選定原始檔變更時更新輸出。正式環境建置請省略 --watch，讓指令寫入輸出後結束：

npx @master/css-cli generate "index.html" --output master.css

部署 index.html、master.css，以及產生的樣式表所參照、位於旁邊的 CSS 資產。請保留相對路徑：只複製 master.css 可能造成其匯入樣式缺少。發布新建置時，請將每一組產生的資產放在一起。

載入部署後的頁面，確認每個樣式表請求都成功。停用 JavaScript 時，段落應保有產生的內距、邊框與表面顏色。掃描類別名稱說明如何納入一般應用程式範圍之外的原始檔。

#若沒有出現樣式

確認頁面渲染的是你編輯的標記，並已載入應用程式樣式表。接著確認建置整合已啟用，且有掃描該原始檔。請保留 p-lg 這樣的完整類別名稱；透過 p-${size} 等片段組合，會讓靜態掃描無法看到最終類別。

若安裝程式回報無法辨識框架，或設定未完成，請依對應的整合指南或 CLI 指南操作。一般應用程式範圍之外的檔案，請參閱掃描類別名稱。

間距變更正常運作後，接著閱讀語法教學，製作具有互動狀態與響應式條件的卡片。