Communitygithub.com

Astro 網站建置器

使用 Astro.build 建立網站的全面技能。當使用者想建立 Astro 網站、需要從 Astro 的免費主題集中選擇合適主題、需要查閱 Astro 文件,或想開發 Astro 元件與頁面時使用。本技能涵蓋主題選擇、文件查閱、專案初始化及 Astro 特定開發模式。

Astro 網站建置器 是什麼?

這項技能「Astro 網站建置器」專為使用 Astro.build 建立網站的開發者或 AI 代理程式所設計。它提供了一套完整的逐步工作流程,從了解使用者需求、從 Astro 官方免費主題集中選擇合適的主題,到專案初始化、元件開發與最佳化部署,無所不包。該技能明確支援 Claude Code、Cursor 或 Codex 等 AI 代理程式共同協作,主要透過 web_fetch 工具從 astro.build 的主題頁面獲取資訊,並參考內建文件 `references/astro_docs.md` 或擷取完整的 LLM 友善文件來解答語法與配置問題。其核心優勢在於引導代理程式遵循 Astro 的最佳實務,例如優先保持元件靜態、使用島嶼架構 (Islands architecture) 和 Astro 的圖片元件來最佳化效能,同時鼓勵使用 TypeScript 以獲得更好的開發體驗。此外,它也提供了常見情境的範例工作流程,如建置部落格、作品集或文件網站,並包含疑難排解章節,幫助快速解決「模組找不到」、「頁面未渲染」或「樣式未套用」等常見問題。總體而言,這項技能確保 AI 代理程式能以結構化、一致且高效的方式協助使用者完成 Astro 專案的各個階段。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GanderBite/relay/tree/HEAD/.claude/skills/astro-builder

在你喜歡的 AI 中提問

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

說明文件

Astro 網站建置器 是做什麼的?

本技能協助您使用 Astro.build 建立網站,引導您完成主題選擇、文件查閱以及開發最佳實務。每當使用者提到使用 Astro 建立網站、想要建立網站,或需要 Astro 特定功能的協助時,請使用此技能。

何時使用此技能

在以下情況啟動此技能:

  • 使用者在其請求中提到「Astro」或「astro.build」
  • 使用者想要建立網站,且 Astro 是合適的選擇(部落格、文件網站、作品集、行銷網站等)
  • 使用者需要為其 Astro 專案選擇主題
  • 使用者需要 Astro 元件、路由或設定方面的協助
  • 使用者想要將 React、Vue 或其他框架與 Astro 整合
  • 使用者需要查閱 Astro 的文件或最佳實務

工作流程概覽

建立 Astro 網站時,請遵循以下流程:

  1. 了解需求 - 決定網站類型及所需功能
  2. 選擇合適主題 - 根據需求從 Astro 的免費主題中選擇
  3. 查閱文件 - 針對特定功能參考 Astro 文件
  4. 初始化專案 - 設定專案結構
  5. 開發元件 - 使用 Astro 的元件架構進行建置
  6. 最佳化與部署 - 遵循效能最佳實務

步驟 1:了解需求

首先,識別網站類型及其需求:

網站類型:

  • 部落格/出版網站
  • 作品集/展示網站
  • 文件網站
  • 行銷/登陸頁面
  • 電子商務網站
  • 公司/企業網站
  • 個人網站

要問的關鍵問題:

  • 網站的主要目的是什麼?
  • 它會有哪些內容類型?(文章、專案、產品等)
  • 需要互動功能嗎?(表單、搜尋、動態內容)
  • 使用者偏好哪些框架?(React、Vue、Svelte 等)
  • 需要特定功能嗎?(深色模式、i18n、CMS 整合)

步驟 2:選擇合適主題

使用 web_fetch 瀏覽免費且相容 React 的主題:

URL: https://astro.build/themes/1/?search=&technology%5B%5D=react&price%5B%5D=free

主題選擇標準:

對於 部落格/出版:

  • 尋找字體排版表現良好的主題
  • 必須支援 Markdown/MDX
  • 應有標籤/分類功能
  • RSS 支援
  • 考慮:astro-paper、astro-blog-template

對於 作品集:

  • 視覺化的專案展示
  • 關於我/聯絡方式區塊
  • 流暢的動畫效果
  • 考慮:astro-portfolio、個人作品集主題

對於 文件網站:

  • 使用 Starlight(Astro 官方文件框架)
  • 功能:搜尋、側邊欄導覽、深色模式、i18n
  • 最適合:技術文件、API 參考、指南

對於 登陸頁面:

  • 包含行動呼籲的主要區域
  • 功能/優勢介紹區塊
  • 聯絡表單
  • 轉換率最佳化

對於 電子商務:

  • 產品列表與篩選
  • 購物車功能
  • 付款整合就緒
  • 產品詳細頁面

行動: 擷取主題頁面、分析可用主題,並推薦 2-3 個最符合使用者需求的選項。說明每個主題為何適合。

步驟 3:查閱 Astro 文件

當您需要特定的 Astro 文件時,請參考以下資源:

  1. 內建參考:references/astro_docs.md - 包含核心 Astro 概念、語法及常見模式
  2. 完整文件:從 https://docs.astro.build/llms-full.txt 擷取以獲得全面資訊

何時參考文件:

  • 元件語法問題 → 參考 astro_docs.md
  • 路由與頁面 → 參考 astro_docs.md
  • 樣式選項 → 參考 astro_docs.md
  • 進階功能 → 從 docs.astro.build 擷取
  • 整合設定 → 從 docs.astro.build 擷取
  • API 細節 → 從 docs.astro.build 擷取

步驟 4:初始化 Astro 專案

使用 Create Astro CLI

# 建立新專案
npm create astro@latest

# 或使用特定範本
npm create astro@latest -- --template <主題 GitHub 使用者名稱>/<主題倉庫>

專案結構設定

初始化後,確保正確的結構:

project/
├── src/
│   ├── components/     # 可重複使用的元件
│   ├── layouts/        # 頁面佈局
│   ├── pages/          # 路由(必要)
│   │   └── index.astro # 首頁
│   ├── content/        # 內容集合(選用)
│   └── assets/         # 最佳化圖片
├── public/             # 靜態資源
├── astro.config.mjs    # 設定檔
├── package.json
└── tsconfig.json

重要: src/pages/ 目錄是路由運作的必要條件。

步驟 5:開發元件與頁面

元件開發模式

  1. 建立元件檔案 於 src/components/
  2. 定義 props 介面(如果使用 TypeScript)
  3. 編寫元件腳本(在建置時執行)
  4. 建立範本(帶有 Astro 語法的 HTML)
  5. 加入範圍樣式(選用)

範例:

---
interface Props {
  title: string;
  description?: string;
}
const { title, description } = Astro.props;
---

<article>
  <h2>{title}</h2>
  {description && <p>{description}</p>}
</article>

<style>
  article {
    padding: 1rem;
    border: 1px solid #ccc;
  }
</style>

頁面開發模式

  1. 建立頁面檔案 於 src/pages/(決定路由)
  2. 匯入必要的元件和佈局
  3. 定義 getStaticPaths() 用於動態路由
  4. 使用元件組合頁面

範例頁面:

---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/Hero.astro';

const title = "我的頁面";
---

<Layout title={title}>
  <Hero />
  <!-- 更多內容 -->
</Layout>

加入互動功能

當您需要客戶端互動時:

  1. 安裝框架整合:npx astro add react
  2. 建立框架元件(.jsx、.vue、.svelte)
  3. 匯入並搭配客戶端指令使用:
---
import ReactComponent from '../components/ReactComponent.jsx';
---

<!-- 靜態(無 JS) -->
<ReactComponent />

<!-- 具互動性 -->
<ReactComponent client:load />
<!-- 選項:client:idle、client:visible、client:media -->

步驟 6:依需要參考文件

在編寫程式碼之前,請先閱讀 references/astro_docs.md 中的相關章節:

  • 元件問題 → 閱讀「元件語法」章節
  • 路由問題 → 閱讀「路由」章節
  • 樣式 → 閱讀「樣式」章節
  • 圖片 → 閱讀「圖片與資源」章節
  • 設定 → 閱讀「設定」章節

對於進階主題,請擷取完整文件:

web_fetch: https://docs.astro.build/llms-full.txt

最佳實務

效能最佳化

  1. 預設保持元件靜態 - 僅在真正需要時才加入 client:*
  2. 使用 Astro 的 Image 元件 - 自動最佳化
  3. 利用島嶼架構 - 預設使用最少的 JavaScript
  4. 程式碼分割 - Astro 會自動按頁面分割

開發工作流程

  1. 從結構開始 - 先設定佈局和基本頁面
  2. 元件驅動 - 建立可重複使用的元件
  3. 型別安全 - 使用 TypeScript 處理 props 以獲得更好的開發體驗
  4. 內容集合 - 用於型別安全的內容管理
  5. 本地測試 - 頻繁執行 npm run dev

要遵循的常見模式

  • 使用佈局來維持一致的頁面結構
  • 建立 SEO 元件來處理 meta 標籤
  • 設定適當的 TypeScript 介面
  • 實作適當的錯誤頁面(404、500)
  • 為圖片加上適當的 alt 文字
  • 使用語意化的 HTML

疑難排解

常見問題

「找不到模組」

  • 確保匯入路徑正確
  • 檢查整合是否已安裝
  • 確認 astro.config.mjs 有正確的整合設定

「頁面未渲染」

  • 確認檔案位於 src/pages/ 目錄中
  • 檢查 frontmatter 中的語法錯誤
  • 確保使用正確的副檔名(.astro、.md、.mdx)

「樣式未套用」

  • 範圍樣式僅套用至元件本身的 HTML
  • 使用 is:global 來套用全域樣式
  • 如果使用 Tailwind,請檢查 Tailwind 設定

「元件不具互動性」

  • 為框架元件加入 client:* 指令
  • 確保已安裝整合(例如 @astrojs/react)
  • 檢查瀏覽器主控台是否有 JavaScript 錯誤

資源

腳本

  • scripts/theme_analyzer.py - 幫助從 Astro 官方主題頁面擷取和分析主題。可用於以程式化方式根據技術和價格篩選條件探索主題選項。

參考資料

  • references/astro_docs.md - 請優先閱讀此文件,以了解核心 Astro 概念、元件語法、路由、樣式和常見模式。這是 Astro 開發的主要參考資料。

外部資源

範例工作流程

範例 1:建立部落格

使用者:「我想用 Astro 和 React 建立一個部落格」

工作流程:

  1. 確認需求:部落格網站、需要 React 支援、想要免費主題
  2. 擷取主題:web_fetch https://astro.build/themes/1/?technology%5B%5D=react&price%5B%5D=free
  3. 推薦主題:建議 2-3 個部落格導向的主題並附上說明
  4. 閱讀 references/astro_docs.md 以參考元件模式
  5. 引導設定:提供安裝指令和結構
  6. 協助建置:建立文章佈局、列表頁面、個別文章頁面
  7. 加入互動:示範如何使用 client:load 加入 React 元件,例如留言功能

範例 2:作品集網站

使用者:「使用 https://astro.build/ 為我建立一個作品集網站」

工作流程:

  1. 釐清需求:要展示什麼?(專案、技能、經歷?)
  2. 從 Astro 主題頁面擷取作品集主題
  3. 根據使用者的領域(開發者、設計師等)推薦最佳匹配
  4. 從 references/astro_docs.md 閱讀元件語法
  5. 使用選定的主題設定專案結構
  6. 建立/自訂元件(主要區域、專案網格、關於我、聯絡方式)
  7. 如果需要,加入流暢的轉場動畫
  8. 使用 Astro 的 Image 元件最佳化圖片

範例 3:文件網站

使用者:「我需要一個具有搜尋和深色模式功能的文件網站」

工作流程:

  1. 確認需求:文件網站、需要搜尋和深色模式
  2. 推薦 Starlight(Astro 官方文件框架)
  3. 展示設定:npm create astro@latest -- --template starlight
  4. 從完整 Astro 文件參考 Starlight 文件
  5. 設定側邊欄導覽結構
  6. 設定內容結構
  7. 啟用深色模式(內建)
  8. 設定搜尋(內建,使用 Pagefind)

關鍵提醒

  1. 回答元件或語法問題前,務必先閱讀 references/astro_docs.md
  2. 當使用者需要起點時,從 Astro 主題頁面擷取主題
  3. 必要時使用 web_fetch 取得完整文件
  4. 保持簡單 - Astro 設計得直接明瞭;不要過度複雜化
  5. 島嶼架構 - 記住元件預設是靜態的
  6. 型別安全 - 鼓勵使用 TypeScript 以獲得更好的開發體驗

成功標準

當滿足以下條件時,Astro 專案即正確設定完成:

  • ✅ 專案結構遵循 Astro 慣例
  • ✅ 存在 src/pages/ 目錄,且至少包含 index.astro
  • ✅ 根據需求選擇了合適的主題
  • ✅ 元件遵循 Astro 語法模式
  • ✅ 僅在必要處加入客戶端互動
  • ✅ 為元件 props 定義了 TypeScript 介面
  • ✅ 使用 Astro 的 Image 元件最佳化圖片
  • ✅ 使用 npm run dev 可成功執行網站

相關技能