Astro v6 架构规则(严格模式)
按 Astro 严格规则开发前端:坚持静态优先与岛屿架构,仅交互单元用框架组件并显式选最低优先级的 client 指令,数据逻辑放服务端,最小化客户端脚本与状态。
完整提示词
# Astro v6 架构规则(严格模式)
## 1. 核心理念
- 遵循 Astro 的“以 HTML 为先 / 默认零 JavaScript”原则:
- 除非明确需要交互性,否则所有内容都是静态 HTML。
- JavaScript 是一种成本 → 仅在能为用户带来真实价值时才添加。
- 始终以“岛屿架构(Islands Architecture)”思维思考:
- 页面是静态 HTML
- 交互部分是隔离的“岛屿”
- 永远不要将整个页面视为一个应用
- 在编写任何 JavaScript 之前,始终先问:
“这个问题能否用 HTML + CSS 或服务端逻辑解决?”
---
## 2. 组件模型
- 使用 `.astro` 组件来处理:
- 布局
- 组合
- 静态 UI
- 数据获取
- 服务端逻辑(frontmatter)
- `.astro` 组件:
- 在构建时或服务端运行
- 默认不发送 JavaScript
- 必须保持框架无关性
- 绝对禁止:
- 在 `.astro` 文件中使用 React/Vue/Svelte 的 hooks
---
## 3. 岛屿(交互式组件)
- 仅在需要交互时使用框架组件(React、Vue、Svelte 等)。
- 将每个交互式组件视为一个隔离的岛屿:
- 独立
- 自包含
- 范围最小化
- 禁止:
- 对整个页面或布局进行 hydration
- 将大型组件树包裹在一个单一岛屿中
- 在循环中不必要地创建大量小型岛屿
- 推荐:
- 使用静态方式渲染列表
- 仅对最小的交互单元进行 hydration
---
## 4. Hydration 策略(关键)
- 始终使用 `client:*` 指令显式定义 hydration。
- 选择尽可能低的优先级:
- `client:load`
→ 仅用于关键的、首屏以上交互内容
- `client:idle`
→ 用于页面加载后的次要 UI
- `client:visible`
→ 用于首屏以下或重量级组件
- `client:media`
→ 用于响应式 / 条件性 UI
- `client:only`
→ 仅在 SSR 出现问题时使用(如 window、localStorage 等)
- 默认规则:
❌ 永远不要默认使用 `client:load`
✅ 优先使用 `client:visible` 或 `client:idle`
- Hydration 是一种性能预算:
- 每个岛屿都会增加 JavaScript
- 保持总 JS 体积最小
📌 Astro 不会对组件进行 hydration,除非通过 `client:*` 明确指定 :contentReference[oaicite:0]{index=0}
---
## 5. 服务端 vs 客户端逻辑
- 优先在服务端逻辑中(在 `.astro` frontmatter 内)处理:
- 数据获取
- 数据转换
- 过滤 / 排序
- 衍生值计算
- 仅在以下情况使用客户端状态:
- 用户交互确实需要
- 需要实时更新
- 避免:
- 在客户端重复服务端逻辑
- 将服务端逻辑移入岛屿中
---
## 6. 状态管理
- 除非绝对必要,否则避免使用客户端状态。
- 如果必须使用:
- 仅在岛屿内部限定状态作用域
- 不要创建全局应用状态,除非确实需要
- 对于跨岛屿状态:
- 使用轻量级共享存储(例如 nano stores)
- 默认避免使用重型全局状态系统
---
## 7. 性能约束(硬性规则)
- 最小化发送到客户端的 JavaScript:
- Astro 仅对已 hydration 的组件加载 JS :contentReference[oaicite:1]{index=1}
- 推荐:
- 静态渲染
- 部分 hydration
- 懒加载 hydration
- 避免:
- 对大型列表进行 hydration
- 在循环中重复创建岛屿
- 过度使用 `client:load`
- 每个岛屿:
- 拥有独立的打包文件
- 独立加载
- 应保持小巧且专注 :contentReference[oaicite:2]{index=2}
---
## 8. 文件与项目结构
- `/pages`
- 入口点(SSG/SSR)
- 不包含客户端逻辑
- `/components`
- 共享 UI
- 岛屿存放于此
- `/layouts`
- 仅用于静态包装
- `/content`
- Markdown / CMS 数据
- 保持 `.astro` 文件专注于组合,而非行为
---
## 9. 反模式(严格禁止)
- ❌ 在 `.astro` 中使用 hooks
- ❌ 将 Astro 变成 SPA 架构
- ❌ 对整个布局/页面进行 hydration
- ❌ 处处使用 `client:load`
- ❌ 将列表映射为已 hydration 的组件
- ❌ 使用客户端 JS 解决静态问题
- ❌ 用客户端逻辑替代服务端逻辑
---
## 10. 推荐模式
- ✅ 以静态为先的渲染
- ✅ 最小化、隔离的岛屿
- ✅ 懒加载 hydration(`visible`、`idle`)
- ✅ 服务端计算
- ✅ HTML + CSS 优先于 JS
- ✅ 渐进式增强
---
## 11. 决策框架(非常重要)
对于每个功能:
1. 这个功能能否用静态 HTML 实现?
→ 是 → 使用 `.astro`
2. 是否需要交互?
→ 否 → 保持静态
3. 是否需要 JS?
→ 是 → 创建一个岛屿
4. 应该何时加载?
→ 选择最低优先级的 `client:*`
---
## 12. 思维模型(不可协商)
- Astro 不是:
- Next.js
- SPA 框架
- 以 React 为中心的系统
- Astro 是:
- 以静态为先的渲染器
- 支持部分 hydration 的系统
- 以性能为先的架构
- 正确思维:
❌ “构建一个应用”
✅ “发送 HTML + 少量 JS”可替换内容
- [oaicite:0]
- [oaicite:1]
- [oaicite:2]
分类与标签
编程开发、编程开发