Astro.js框架

# Astro v6 架构规则（严格模式）

## 1. 核心理念

- 遵循 Astro 的“HTML 优先 / 默认零 JavaScript”原则：
  - 除非明确需要交互性，否则一切皆为静态 HTML。
  - JavaScript 是一种成本 → 仅在能创造真实用户价值时才添加。

- 始终以“群岛架构”思考：
  - 页面是静态 HTML
  - 交互部分是独立的群岛
  - 绝不将整个页面视为一个应用

- 在编写任何 JavaScript 之前，请务必自问：
  “这能用 HTML + CSS 或服务器端逻辑解决吗？”

---

## 2. 组件模型

- 使用 `.astro` 组件用于：
  - 布局
  - 组合
  - 静态 UI
  - 数据获取
  - 服务器端逻辑（frontmatter）

- `.astro` 组件：
  - 在构建时或服务器端运行
  - 默认不发送 JavaScript
  - 必须保持与框架无关

- 绝不（NEVER）在 `.astro` 内部使用 React/Vue/Svelte hooks

---

## 3. 群岛（交互式组件）

- 仅将框架组件（React, Vue, Svelte 等）用于交互性。

- 将每个交互式组件视为一个独立的群岛：
  - 独立
  - 自包含
  - 最小范围

- 绝不（NEVER）：
  - 激活（Hydrate）整个页面或布局
  - 将大型树包裹在单个群岛中
  - 不必要地在循环中创建许多小群岛

- 优先选择：
  - 静态列表渲染
  - 仅激活最小的交互单元

---

## 4. 激活策略（关键）

- 始终使用 `client:*` 指令明确定义激活。

- 选择尽可能低的优先级：

  - `client:load`
    → 仅用于关键的、首屏交互性

  - `client:idle`
    → 用于页面加载后的次要 UI

  - `client:visible`
    → 用于非首屏或重型组件

  - `client:media`
    → 用于响应式 / 条件 UI

  - `client:only`
    → 仅当 SSR 破坏时（window, localStorage 等）

- 默认规则：
  ❌ 绝不默认使用 `client:load`
  ✅ 优先选择 `client:visible` 或 `client:idle`

- 激活是一种性能预算：
  - 每个群岛都会增加 JS
  - 保持总 JS 量最小

📌 Astro 不会激活组件，除非通过 `client:*` 明确告知 :contentReference[oaicite:0]{index=0}  

---

## 5. 服务器端与客户端逻辑

- 优先选择服务器端逻辑（在 `.astro` frontmatter 内部）用于：
  - 数据获取
  - 转换
  - 过滤 / 排序
  - 派生值

- 仅在以下情况使用客户端状态：
  - 用户交互需要它
  - 需要实时更新

- 避免：
  - 在客户端重复逻辑
  - 将服务器逻辑移入群岛

---

## 6. 状态管理

- 除非绝对必要，否则避免客户端状态。

- 如果需要：
  - 仅将状态限定在群岛内部
  - 除非需要，否则不要创建全局应用状态

- 对于跨群岛状态：
  - 使用轻量级共享存储（例如，nano stores）
  - 默认避免重量级全局状态系统

---

## 7. 性能约束（硬性规则）

- 最小化发送到客户端的 JavaScript：
  - Astro 仅为激活的组件加载 JS :contentReference[oaicite:1]{index=1}  

- 优先选择：
  - 静态渲染
  - 部分激活
  - 延迟激活

- 避免：
  - 激活大型列表
  - 在循环中重复群岛
  - 过度使用 `client:load`

- 每个群岛：
  - 拥有自己的 bundle
  - 独立加载
  - 应保持小巧和专注 :contentReference[oaicite:2]{index=2}  

---

## 8. 文件与项目结构

- `/pages`
  - 入口点 (SSG/SSR)
  - 无客户端逻辑

- `/components`
  - 共享 UI
  - 群岛在此处

- `/layouts`
  - 仅静态包装器

- `/content`
  - Markdown / CMS 数据

- 保持 `.astro` 文件专注于组合，而非行为

---

## 9. 反模式（严格禁止）

- ❌ 在 `.astro` 中使用 hooks
- ❌ 将 Astro 变成 SPA 架构
- ❌ 激活整个布局/页面
- ❌ 随处使用 `client:load`
- ❌ 将列表映射到激活的组件中
- ❌ 使用客户端 JS 解决静态问题
- ❌ 用客户端逻辑替换服务器逻辑

---

## 10. 首选模式

- ✅ 静态优先渲染
- ✅ 最小、独立的群岛
- ✅ 延迟激活（`visible`, `idle`）
- ✅ 服务器端计算
- ✅ JS 之前优先 HTML + CSS
- ✅ 渐进增强

---

## 11. 决策框架（非常重要）

对于每个功能：

1. 这能是静态 HTML 吗？
   → 是 → 使用 `.astro`

2. 它需要交互吗？
   → 否 → 保持静态

3. 它需要 JS 吗？
   → 是 → 创建一个群岛

4. 它应该何时加载？
   → 选择最低优先级的 `client:*`

---

## 12. 心智模型（不可协商）

- Astro 不是：
  - Next.js
  - SPA 框架
  - React 优先系统

- Astro 是：
  - 静态优先渲染器
  - 部分激活系统
  - 性能优先架构

- 思考方式：
  ❌ “构建一个应用”
  ✅ “发送 HTML + 少量 JS”