约束 Astro v6 项目写法的规则：默认静态 HTML，只为必要交互使用孤岛组件，严格控制 JavaScript。
# 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”# Astro v6 Architecture Rules (Strict Mode)
## 1. Core Philosophy
- Follow Astro’s “HTML-first / zero JavaScript by default” principle:
- Everything is static HTML unless interactivity is explicitly required.
- JavaScript is a cost → only add when it creates real user value.
- Always think in “Islands Architecture”:
- The page is static HTML
- Interactive parts are isolated islands
- Never treat the whole page as an app
- Before writing any JavaScript, always ask:
"Can this be solved with HTML + CSS or server-side logic?"
---
## 2. Component Model
- Use `.astro` components for:
- Layout
- Composition
- Static UI
- Data fetching
- Server-side logic (frontmatter)
- `.astro` components:
- Run at build-time or server-side
- Do NOT ship JavaScript by default
- Must remain framework-agnostic
- NEVER use React/Vue/Svelte hooks inside `.astro`
---
## 3. Islands (Interactive Components)
- Only use framework components (React, Vue, Svelte, etc.) for interactivity.
- Treat every interactive component as an isolated island:
- Independent
- Self-contained
- Minimal scope
- NEVER:
- Hydrate entire pages or layouts
- Wrap large trees in a single island
- Create many small islands in loops unnecessarily
- Prefer:
- Static list rendering
- Hydrate only the minimal interactive unit
---
## 4. Hydration Strategy (Critical)
- Always explicitly define hydration using `client:*` directives.
- Choose the LOWEST possible priority:
- `client:load`
→ Only for critical, above-the-fold interactivity
- `client:idle`
→ For secondary UI after page load
- `client:visible`
→ For below-the-fold or heavy components
- `client:media`
→ For responsive / conditional UI
- `client:only`
→ ONLY when SSR breaks (window, localStorage, etc.)
- Default rule:
❌ Never default to `client:load`
✅ Prefer `client:visible` or `client:idle`
- Hydration is a performance budget:
- Every island adds JS
- Keep total JS minimal
📌 Astro does NOT hydrate components unless explicitly told via `client:*` :contentReference[oaicite:0]{index=0}
---
## 5. Server vs Client Logic
- Prefer server-side logic (inside `.astro` frontmatter) for:
- Data fetching
- Transformations
- Filtering / sorting
- Derived values
- Only use client-side state when:
- User interaction requires it
- Real-time updates are needed
- Avoid:
- Duplicating logic on client
- Moving server logic into islands
---
## 6. State Management
- Avoid client state unless strictly necessary.
- If needed:
- Scope state inside the island only
- Do NOT create global app state unless required
- For cross-island state:
- Use lightweight shared stores (e.g., nano stores)
- Avoid heavy global state systems by default
---
## 7. Performance Constraints (Hard Rules)
- Minimize JavaScript shipped to client:
- Astro only loads JS for hydrated components :contentReference[oaicite:1]{index=1}
- Prefer:
- Static rendering
- Partial hydration
- Lazy hydration
- Avoid:
- Hydrating large lists
- Repeated islands in loops
- Overusing `client:load`
- Each island:
- Has its own bundle
- Loads independently
- Should remain small and focused :contentReference[oaicite:2]{index=2}
---
## 8. File & Project Structure
- `/pages`
- Entry points (SSG/SSR)
- No client logic
- `/components`
- Shared UI
- Islands live here
- `/layouts`
- Static wrappers only
- `/content`
- Markdown / CMS data
- Keep `.astro` files focused on composition, not behavior
---
## 9. Anti-Patterns (Strictly Forbidden)
- ❌ Using hooks in `.astro`
- ❌ Turning Astro into SPA architecture
- ❌ Hydrating entire layout/page
- ❌ Using `client:load` everywhere
- ❌ Mapping lists into hydrated components
- ❌ Using client JS for static problems
- ❌ Replacing server logic with client logic
---
## 10. Preferred Patterns
- ✅ Static-first rendering
- ✅ Minimal, isolated islands
- ✅ Lazy hydration (`visible`, `idle`)
- ✅ Server-side computation
- ✅ HTML + CSS before JS
- ✅ Progressive enhancement
---
## 11. Decision Framework (VERY IMPORTANT)
For every feature:
1. Can this be static HTML?
→ YES → Use `.astro`
2. Does it require interaction?
→ NO → Stay static
3. Does it require JS?
→ YES → Create an island
4. When should it load?
→ Choose LOWEST priority `client:*`
---
## 12. Mental Model (Non-Negotiable)
- Astro is NOT:
- Next.js
- SPA framework
- React-first system
- Astro IS:
- Static-first renderer
- Partial hydration system
- Performance-first architecture
- Think:
❌ “Build an app”
✅ “Ship HTML + sprinkle JS”