Astro 网站构建器
此技能通过引导您完成主题选择、文档访问和开发最佳实践,帮助您使用 Astro.build 构建网站。当用户提到使用 Astro 构建、想要创建网站或需要 Astro 特定功能的帮助时,请使用此技能。
何时使用此技能
在以下情况下激活此技能:
- 用户在请求中提到“Astro”或“astro.build”
- 用户想要构建网站,且 Astro 是合适的选择(博客、文档、作品集、营销网站等)
- 用户需要为其 Astro 项目选择主题
- 用户需要 Astro 组件、路由或配置方面的帮助
- 用户想要将 React、Vue 或其他框架与 Astro 集成
- 用户需要访问 Astro 的文档或最佳实践
工作流程概述
构建 Astro 网站时,请遵循以下流程:
- 了解需求 - 确定网站类型和所需功能
- 选择合适的主题 - 根据需求从 Astro 的免费主题中选择
- 访问文档 - 参考 Astro 文档了解特定功能
- 初始化项目 - 设置项目结构
- 开发组件 - 使用 Astro 的组件架构进行构建
- 优化与部署 - 遵循性能最佳实践
步骤 1:了解需求
首先,确定网站的类型及其需求:
网站类型:
- 博客/出版网站
- 作品集/展示网站
- 文档网站
- 营销/着陆页
- 电子商务网站
- 公司/企业网站
- 个人网站
需要询问的关键问题:
- 网站的主要目的是什么?
- 它将包含哪些内容类型?(博客文章、项目、产品等)
- 是否需要交互性?(表单、搜索、动态内容)
- 用户偏好哪些框架?(React、Vue、Svelte 等)
- 是否需要特定功能?(深色模式、国际化、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 官方文档框架)
- 功能:搜索、侧边栏导航、深色模式、国际化
- 适用于:技术文档、API 参考、指南
对于着陆页:
- 带有行动号召的 Hero 部分
- 功能/优势部分
- 联系表单
- 转化优化
对于电子商务:
- 产品列表和筛选
- 购物车功能
- 支付集成就绪
- 产品详情页
操作: 获取主题页面,分析可用主题,并推荐 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 组件处理元标签
- 设置正确的 TypeScript 接口
- 实现正确的错误页面(404、500)
- 为图片添加正确的 alt 文本
- 使用语义化 HTML
故障排除
常见问题
“模块未找到”
- 确保导入路径正确
- 检查集成是否已安装
- 验证
astro.config.mjs是否包含正确的集成设置
“页面未渲染”
- 确认文件位于
src/pages/目录中 - 检查 frontmatter 中是否有语法错误
- 确保文件扩展名正确(.astro、.md、.mdx)
“样式未应用”
- 作用域样式仅应用于组件自身的 HTML
- 使用
is:global定义全局样式 - 如果使用 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阅读组件语法 - 使用所选主题设置项目结构
- 创建/自定义组件(Hero、项目网格、关于、联系)
- 如果需要,添加流畅的过渡效果
- 使用 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成功运行网站