Astro 網站建置器 是做什麼的?
本技能協助您使用 Astro.build 建立網站,引導您完成主題選擇、文件查閱以及開發最佳實務。每當使用者提到使用 Astro 建立網站、想要建立網站,或需要 Astro 特定功能的協助時,請使用此技能。
何時使用此技能
在以下情況啟動此技能:
- 使用者在其請求中提到「Astro」或「astro.build」
- 使用者想要建立網站,且 Astro 是合適的選擇(部落格、文件網站、作品集、行銷網站等)
- 使用者需要為其 Astro 專案選擇主題
- 使用者需要 Astro 元件、路由或設定方面的協助
- 使用者想要將 React、Vue 或其他框架與 Astro 整合
- 使用者需要查閱 Astro 的文件或最佳實務
工作流程概覽
建立 Astro 網站時,請遵循以下流程:
- 了解需求 - 決定網站類型及所需功能
- 選擇合適主題 - 根據需求從 Astro 的免費主題中選擇
- 查閱文件 - 針對特定功能參考 Astro 文件
- 初始化專案 - 設定專案結構
- 開發元件 - 使用 Astro 的元件架構進行建置
- 最佳化與部署 - 遵循效能最佳實務
步驟 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 文件時,請參考以下資源:
- 內建參考:
references/astro_docs.md- 包含核心 Astro 概念、語法及常見模式 - 完整文件:從
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:開發元件與頁面
元件開發模式
- 建立元件檔案 於
src/components/ - 定義 props 介面(如果使用 TypeScript)
- 編寫元件腳本(在建置時執行)
- 建立範本(帶有 Astro 語法的 HTML)
- 加入範圍樣式(選用)
範例:
---
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>
頁面開發模式
- 建立頁面檔案 於
src/pages/(決定路由) - 匯入必要的元件和佈局
- 定義 getStaticPaths() 用於動態路由
- 使用元件組合頁面
範例頁面:
---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/Hero.astro';
const title = "我的頁面";
---
<Layout title={title}>
<Hero />
<!-- 更多內容 -->
</Layout>
加入互動功能
當您需要客戶端互動時:
- 安裝框架整合:
npx astro add react - 建立框架元件(.jsx、.vue、.svelte)
- 匯入並搭配客戶端指令使用:
---
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
最佳實務
效能最佳化
- 預設保持元件靜態 - 僅在真正需要時才加入
client:* - 使用 Astro 的 Image 元件 - 自動最佳化
- 利用島嶼架構 - 預設使用最少的 JavaScript
- 程式碼分割 - Astro 會自動按頁面分割
開發工作流程
- 從結構開始 - 先設定佈局和基本頁面
- 元件驅動 - 建立可重複使用的元件
- 型別安全 - 使用 TypeScript 處理 props 以獲得更好的開發體驗
- 內容集合 - 用於型別安全的內容管理
- 本地測試 - 頻繁執行
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 開發的主要參考資料。
外部資源
- Astro 主題:https://astro.build/themes/
- Astro 文件(對 LLM 友善):https://docs.astro.build/llms-full.txt
- Astro 文件:https://docs.astro.build
- Astro Discord:https://astro.build/chat
範例工作流程
範例 1:建立部落格
使用者:「我想用 Astro 和 React 建立一個部落格」
工作流程:
- 確認需求:部落格網站、需要 React 支援、想要免費主題
- 擷取主題:
web_fetch https://astro.build/themes/1/?technology%5B%5D=react&price%5B%5D=free - 推薦主題:建議 2-3 個部落格導向的主題並附上說明
- 閱讀
references/astro_docs.md以參考元件模式 - 引導設定:提供安裝指令和結構
- 協助建置:建立文章佈局、列表頁面、個別文章頁面
- 加入互動:示範如何使用
client:load加入 React 元件,例如留言功能
範例 2:作品集網站
使用者:「使用 https://astro.build/ 為我建立一個作品集網站」
工作流程:
- 釐清需求:要展示什麼?(專案、技能、經歷?)
- 從 Astro 主題頁面擷取作品集主題
- 根據使用者的領域(開發者、設計師等)推薦最佳匹配
- 從
references/astro_docs.md閱讀元件語法 - 使用選定的主題設定專案結構
- 建立/自訂元件(主要區域、專案網格、關於我、聯絡方式)
- 如果需要,加入流暢的轉場動畫
- 使用 Astro 的 Image 元件最佳化圖片
範例 3:文件網站
使用者:「我需要一個具有搜尋和深色模式功能的文件網站」
工作流程:
- 確認需求:文件網站、需要搜尋和深色模式
- 推薦 Starlight(Astro 官方文件框架)
- 展示設定:
npm create astro@latest -- --template starlight - 從完整 Astro 文件參考 Starlight 文件
- 設定側邊欄導覽結構
- 設定內容結構
- 啟用深色模式(內建)
- 設定搜尋(內建,使用 Pagefind)
關鍵提醒
- 回答元件或語法問題前,務必先閱讀
references/astro_docs.md - 當使用者需要起點時,從 Astro 主題頁面擷取主題
- 必要時使用 web_fetch 取得完整文件
- 保持簡單 - Astro 設計得直接明瞭;不要過度複雜化
- 島嶼架構 - 記住元件預設是靜態的
- 型別安全 - 鼓勵使用 TypeScript 以獲得更好的開發體驗
成功標準
當滿足以下條件時,Astro 專案即正確設定完成:
- ✅ 專案結構遵循 Astro 慣例
- ✅ 存在
src/pages/目錄,且至少包含 index.astro - ✅ 根據需求選擇了合適的主題
- ✅ 元件遵循 Astro 語法模式
- ✅ 僅在必要處加入客戶端互動
- ✅ 為元件 props 定義了 TypeScript 介面
- ✅ 使用 Astro 的 Image 元件最佳化圖片
- ✅ 使用
npm run dev可成功執行網站