在 Astro 設定 Master CSS

透過共用 CSS 進入點，將 Master CSS 接入 Astro 網站。整合支援靜態、執行階段與漸進式傳遞；頁面渲染仍由 Astro 負責。

#安裝

1. #加入 Master CSS

   在既有的 Astro 專案中，從專案根目錄執行安裝程式。預設使用靜態模式：掃描完整的類別字串，並輸出一般 CSS。

   npm create @master/css@2.0.0 -- --framework astro --yes

2. #連接樣式表

   安裝程式會建立獨立的 CSS 進入點：

   src/styles/global.css

   @import '@master/css';

   從頁面或版面配置的 frontmatter 匯入它。共用版面配置會將樣式傳遞給所有使用它的頁面。在 astro.config.mjs 中，請將 Master CSS 整合與專案既有的整合一併保留。

3. #開始使用 Master CSS

   啟動開發伺服器。從頁面 frontmatter 匯入 src/styles/global.css，再加入段落。若多個頁面都需要樣式，請在共用版面配置中使用相同匯入。

src/pages/index.astro

---import '../styles/global.css'---<html lang="en">  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <title>Hello Master CSS</title>  </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 的內距。

#檢查設定

執行 npm run dev，將 p-md 改成 p-lg，確認內距從 1rem 增加為 1.5rem。改回原值，再測試正式環境頁面：

npm run buildnpm run preview

停用 JavaScript 並重新載入。段落應保有內距、圓角與浮起的表面。若未出現樣式，請確認頁面或其版面配置有匯入 global.css，且 Astro 設定包含 Master CSS 整合。自訂定義與作用範圍樣式請參閱全域樣式。

#使用 CLI 建置靜態 CSS

這是 Astro 整合的替代方式。從 astro.config.mjs 移除 Master CSS 的註冊，保留其他整合，並移除頁面或版面配置中的 global.css 匯入。安裝 CLI：

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

在專案根目錄建立原始碼進入點。專案的自訂定義也放在這裡：

@import '@master/css';

從頁面或共用版面配置的 <head> 連結產生的樣式表：

<link rel="stylesheet" href="/master.css" />

先產生 CSS，再建置 Astro：

npx @master/css-cli generate "src/**/*.{astro,html,js,jsx,ts,tsx,vue,svelte}" --output public/master.cssnpm run buildnpm run preview

開發時，在產生指令加入 --watch，並在第二個終端機執行 npm run dev。Astro 會將 public/ 複製到建置輸出；請一起部署產生的樣式表及其匯入資產。若網站有設定基底路徑，請將該路徑加在樣式表網址前。停用 JavaScript，驗證段落的樣式。

#選擇其他渲染模式

預設使用靜態模式。其他模式的頁面執行階段指令碼會由整合注入，不需要額外的瀏覽器啟動程式：

npm create @master/css@2.0.0 -- --framework astro --mode runtime --yes

document.querySelector('#master-check').classList.add('underline')

npm create @master/css@2.0.0 -- --framework astro --mode progressive --yes