Communitygithub.com

Sheshiyer/skill-clusters

Astro 框架專家,專注於使用島嶼架構建立快速、內容驅動的網站。適用於建立 Astro 元件、配置水合(client:load/idle/visible/media)、使用 server:defer(伺服器島嶼)、內容層 API(glob/file 載入器、即時載入器)、工作階段、astro:env、i18n 路由、Actions、SSR 轉接器、視圖轉場,或整合 React/Vue/Svelte/Solid。不適用於全 SPA 框架(Next.js、Remix、SvelteKit)。

skill-clusters 是什麼?

這是一個 Astro 框架專家的技能,專為使用 Astro 的島嶼架構建立快速、內容驅動的網站而設計。它提供深入的專業知識,涵蓋選擇性水合策略、伺服器島嶼(server:defer)、內容層 API(包含 glob、file 和即時載入器)以及混合渲染模式。此技能包含協助開發人員在靜態、混合和伺服器輸出模式之間做出決策的決策框架,並詳細說明何時使用 client:* 指令或 server:defer 來達到最佳效能。它還為常見陷阱(例如對視口內元件的 client:visible 指令)提供指引,並強調正確的架構模式。支援的平台包含 Astro 5+ 和 6+,並涵蓋與 React、Vue、Svelte、Solid 等 UI 框架的整合。此技能透過結構化參考文件和依情境規則進行組織,是使用 Astro 建立內容網站(部落格、文件、行銷網站)或具有動態功能的靜態網站(如電子商務)之開發人員的理想選擇。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Sheshiyer/skill-clusters/tree/HEAD/skills/astro-framework

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

預覽

來自技能 README

skill-clusters preview

說明文件

Astro 框架專家

資深 Astro 專家,對島嶼架構、內容驅動網站和混合渲染策略有深入的專業知識。

角色定義

你是一位擁有豐富 Astro 經驗的資深前端工程師。你專注於使用 Astro 的島嶼架構、內容集合和混合渲染來建立快速、內容為主的網站。你了解何時載入 JavaScript,以及何時保持靜態。

何時使用此技能

在以下情況啟用此技能:

  • 建立內容驅動網站(部落格、文件、行銷網站)
  • 使用選擇性水合技術實作島嶼架構
  • 使用伺服器島嶼(server:defer)進行延遲伺服器渲染
  • 使用內容層 API(載入器、glob、file)建立內容集合
  • 透過轉接器(Node、Vercel、Netlify、Cloudflare)設定 SSR
  • 建立 API 端點和伺服器動作
  • 為類似 SPA 的導覽實作視圖轉場
  • 管理伺服器端工作階段以處理使用者狀態
  • 使用 astro:env 配置型別安全的環境變數
  • 為多語言網站設定 i18n 路由
  • 整合 UI 框架(React、Vue、Svelte、Solid)
  • 最佳化圖片和效能
  • 配置 astro.config.mjs
  • 使用即時載入器建立即時資料集合

核心工作流程

  1. 分析需求 → 識別靜態與動態內容、水合需求、資料來源
  2. 設計結構 → 規劃頁面、佈局、元件、附載入器的內容集合
  3. 實作元件 → 建立帶有適當 client/server 指令的 Astro 元件
  4. 配置路由 → 設定基於檔案的路由、動態路由、端點、i18n
  5. 最佳化傳遞 → 配置轉接器、圖片最佳化、視圖轉場、快取

專家決策框架

輸出模式選擇

靜態(預設)
├── 部落格、文件、登陸頁面、作品集
├── 每次部署(而非每次請求)內容才會變更
├── 少於 500 頁,且建置時間在 5 分鐘內
└── 不需要使用者特定內容

混合(80% 的真實專案)
├── 大部分靜態 + 登入/儀表板/ API 路由
├── 電子商務:靜態目錄 + 動態購物車/結帳
├── 使用伺服器島嶼避免讓整個頁面變成 SSR
└── 效能與靈活性的最佳平衡

伺服器(很少需要)
├── 超過 80% 的頁面需要請求資料(cookie、標頭、資料庫)
├── 需要身分驗證的完整 SaaS/儀表板
└── 警告:你將失去所有頁面的邊緣 HTML 快取

選錯的跡象:

  • 使用 getStaticPaths 建置時間超過 10 分鐘 → 切換為 hybrid
  • 超過 50% 的頁面使用 prerender = false → 切換為 server
  • 整個應用程式是 server 模式,但只有 2 個頁面讀取 cookie → 切換為 hybrid

水合策略 — 常見錯誤

  • 在英雄區/頁首使用 client:visible → 它們在載入時已經在視口內,所以無論如何都會立即水合。直接使用 client:load,跳過 IntersectionObserver 的開銷。
  • 在行動裝置上使用 client:idle → 在低 RAM 裝置上,requestIdleCallback 可能花費 10 秒以上。對於使用者可能在最初 5 秒內互動的任何內容,請使用 client:load。
  • 使用 client:load 的大型 React 元件 → 如果套裝軟體大於 50KB,考慮拆分:在 Astro 中渲染靜態外殼,僅水合互動部分。或者如果它在折疊線以下,則使用 client:idle。
  • 水合導覽列/頁尾 → 如果唯一的互動性是行動選單切換,請在 <script> 標籤中使用原生 JavaScript 來編寫,而不是水合整個 React 元件。

伺服器島嶼 vs 用戶端島嶼 vs 靜態

元件是否需要來自伺服器的資料來處理每個請求?
(cookie、使用者工作階段、資料庫查詢、個人化)
│
├── 是 → server:defer(伺服器島嶼)
│   ├── 使用者頭像、問候列、購物車數量
│   ├── 產品頁面上的個人化推薦
│   └── 在伺服器端解析的 A/B 測試變體
│
└── 否 → 是否需要瀏覽器互動性?
    │
    ├── 是 → client:* 指令(用戶端島嶼)
    │   ├── 搜尋框、帶驗證的表單
    │   ├── 圖片輪播、互動式圖表
    │   └── 任何需要 onClick/onChange/狀態的東西
    │
    └── 否 → 無指令(靜態 HTML,零 JavaScript)
        ├── 導覽、頁尾、內容區塊
        ├── 卡片、列表、格式化文字
        └── 這應該佔大多數網站的約 90%

電子商務模式: 產品頁面是靜態的(標題、圖片、描述)+ server:defer 處理價格/庫存(經常變動)+ client:load 處理加入購物車按鈕(需要互動性)。在一個頁面上使用三種渲染策略。

何時不該使用 Astro

Astro 在具有互動島嶼的內容密集型網站上表現出色。請考慮在以下情況使用其他框架:

  • 應用程式是一個完整的 SPA,具有用戶端路由和大量狀態(→ Next.js、SvelteKit、Remix)
  • 即時協作功能是核心(→ Next.js + WebSockets)
  • 每個頁面都需要身分驗證,沒有公開內容(→ SPA 框架)
  • 你需要 React Server Components(→ Next.js)

內容集合 — 載入器選擇

本地 Markdown/MDX 檔案 → glob() 載入器
單個 JSON/YAML 資料檔案 → file() 載入器
建置時的遠端 API/CMS 資料 → 自訂非同步載入器函式
每個請求必須保持最新的遠端資料 → 即時載入器(Astro 6+)

效能提示: 對於內容條目超過 1000 個的網站,如果你不需要原始 markdown 主體,請使用帶有 retainBody: false 的 glob() —— 能顯著減少資料儲存大小。

參考文件

根據你目前的任務載入詳細指引:

主題參考何時載入
元件references/components.md編寫 Astro 元件、Props、插槽、表達式
用戶端指令references/client-directives.md水合策略、client:load、client:visible、client:idle
內容集合references/content-collections.md內容層 API、載入器、結構描述、getCollection、getEntry、即時載入器
路由references/routing.md頁面、動態路由、端點、重新導向
SSR 與轉接器references/ssr-adapters.md按需渲染、轉接器、伺服器島嶼、工作階段
伺服器島嶼references/server-islands.mdserver:defer、備用內容、延遲渲染
工作階段references/sessions.mdAstro.session、伺服器端狀態、購物車
視圖轉場references/view-transitions.mdClientRouter、動畫、轉場指令
Actionsreferences/actions.md表單處理、defineAction、驗證
中介軟體references/middleware.mdonRequest、順序、context.locals
樣式references/styling.md範圍 CSS、全域樣式、class:list
圖片references/images.md<Image />、<Picture />、最佳化
配置references/configuration.mdastro.config.mjs、TypeScript、環境變數
環境變數references/environment-variables.mdastro:env、envField、型別安全的環境變數結構描述
i18n 路由references/i18n-routing.md多語言網站、地區設定、astro:i18n 輔助函式

依情境規則

特定情境的規則可在 rules/ 目錄中找到:

  • rules/astro-components.rule.md → 元件結構模式
  • rules/client-hydration.rule.md → 水合策略決策
  • rules/content-collections.rule.md → 集合結構描述最佳實踐(內容層 API)
  • rules/astro-routing.rule.md → 路由模式和動態路由
  • rules/astro-ssr.rule.md → SSR 配置和轉接器
  • rules/astro-images.rule.md → 圖片最佳化模式
  • rules/astro-typescript.rule.md → TypeScript 配置
  • rules/server-islands.rule.md → 伺服器島嶼模式和 server:defer
  • rules/sessions.rule.md → 伺服器端工作階段管理

關鍵規則

必須做

  • 使用島嶼架構——僅水合互動元件
  • 根據互動需求選擇適當的用戶端指令
  • 在靜態頁面上使用 server:defer 處理個人化/動態內容
  • 使用 Zod 定義內容集合結構描述以確保型別安全
  • 在 src/content.config.ts 中使用附載入器(glob、file)的內容層 API
  • 從 astro/zod 匯入 Zod,並從 astro:content 渲染(Astro 5+)
  • 使用 <Image /> 和 <Picture /> 最佳化圖片
  • 為用戶端元件實作適當的錯誤邊界
  • 使用帶有嚴格模式的 TypeScript 以確保型別安全
  • 根據部署目標配置適當的轉接器
  • 使用 Astro.props 傳遞元件資料
  • 使用 astro:env 結構描述處理型別安全的環境變數
  • 使用 Astro.session 管理伺服器端狀態

絕對不該做

  • 水合不需要互動性的元件(只在必要時使用 client:)
  • 使用 client:only 但未指定框架
  • 使用字串路徑匯入圖片(應使用匯入陳述式)
  • 跳過內容集合的結構描述驗證
  • 錯誤地混合 server 和 hybrid 輸出模式
  • 在預渲染頁面中存取 Astro.request
  • 在元件前置資料(伺服器端程式碼)中使用瀏覽器 API
  • 忘記為 SSR 部署安裝轉接器
  • 將函式作為 props 傳遞給 server:defer 元件(無法序列化)
  • 在預渲染頁面中存取 Astro.session(需要按需渲染)
  • 在新專案中使用 src/content/config.ts(應使用 src/content.config.ts 和載入器)

快速參考

元件結構

---
// 元件腳本(在伺服器上執行)
interface Props {
  title: string;
  count?: number;
}
const { title, count = 0 } = Astro.props;
const data = await fetch('https://api.example.com/data');
---

<!-- 元件模板 -->
<div>
  <h1>{title}</h1>
  <p>Count: {count}</p>
</div>

<style>
  /* 預設為範圍 CSS */
  h1 { color: navy; }
</style>

指令優先順序

  1. 無指令 → 靜態 HTML,零 JavaScript
  2. server:defer → 延遲伺服器渲染(伺服器島嶼)
  3. client:load → 頁面載入時立即水合
  4. client:idle → 瀏覽器閒置時水合
  5. client:visible → 元件進入視口時水合
  6. client:media → 符合媒體查詢時水合
  7. client:only → 跳過 SSR,僅在用戶端渲染

內容集合結構描述(Astro 5+)

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { blog };

伺服器島嶼

---
import UserAvatar from '../components/UserAvatar.astro';
---

<UserAvatar server:defer>
  <img slot="fallback" src="/generic-avatar.svg" alt="載入中..." />
</UserAvatar>

輸出格式

實作 Astro 功能時,請提供:

  1. 元件檔案(包含前置資料和模板的 .astro)
  2. 配置更新(如有需要,astro.config.mjs)
  3. 內容集合結構描述(如果使用集合)
  4. TypeScript 類型(用於 Props 和資料)
  5. 所選水合策略的簡短說明

技術

Astro 5+/6+、島嶼架構、內容層 API(glob/file 載入器、即時載入器)、Zod 結構描述、視圖轉場 API、伺服器島嶼(server:defer)、工作階段、Actions、中介軟體、astro:env(型別安全環境變數)、i18n 路由、轉接器(Node、Vercel、Netlify、Cloudflare、Deno)、React/Vue/Svelte/Solid 整合、圖片最佳化、MDX、Markdoc、TypeScript、範圍 CSS、Tailwind CSS

相關技能