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

# Astro v6 架构规则（严格模式） ## 1. 核心理念 - 遵循 Astro 的“HTML优先 / 默认零JavaScript”原则： - 除非明确需要交互性，否则一切均为静态HTML。 - JavaScript 是一种成本，仅在创造真实用户价值时添加。 - 始终以“岛屿架构”思考： - 页面是静态HTML - 交互部分为孤立的岛屿 - 切勿将整个页面视为应用 - 在编写任何JavaScript之前，始终自问：“这个问题能否用HTML + CSS或服务端逻辑解决？” ## 2. 组件模型 - 使用 `.astro` 组件处理： - 布局 - 组合 - 静态UI - 数据获取 - 服务端逻辑（frontmatter） - `.astro` 组件： - 在构建时或服务端运行 - 默认不加载JavaScript - 必须保持框架无关性 - 切勿在 `.astro` 中使用 React/Vue/Svelte 钩子 ## 3. 岛屿（交互式组件） - 仅使用框架组件（React、Vue、Svelte等）处理交互性。 - 将每个交互式组件视为孤立的岛屿： - 独立 - 自包含 - 最小作用域 - 切勿： - 水合整个页面或布局 - 将大型树结构包裹在单个岛屿中 - 在循环中不必要地创建多个小岛屿 - 优先选择： - 静态列表渲染 - 仅水合最小交互单元 ## 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量最小 ## 5. 服务端与客户端逻辑 - 优先使用服务端逻辑（在 `.astro` frontmatter 中）处理： - 数据获取 - 转换 - 过滤/排序 - 派生值 - 仅在以下情况使用客户端状态： - 用户交互需要 - 需要实时更新 - 避免： - 在客户端重复逻辑 - 将服务端逻辑移入岛屿 ## 6. 状态管理 - 除非绝对必要，否则避免客户端状态。 - 如果需要： - 将状态限定在岛屿内部 - 除非必要，否则不要创建全局应用状态 - 对于跨岛屿状态： - 使用轻量级共享存储（例如 nano stores） - 默认避免重型全局状态系统 ## 7. 性能约束（硬性规则） - 最小化发送到客户端的JavaScript： - Astro 仅加载水合组件的JS - 优先选择： - 静态渲染 - 部分水合 - 懒加载水合 - 避免： - 水合大型列表 - 在循环中重复岛屿 - 过度使用 `client:load` - 每个岛屿： - 拥有自己的包 - 独立加载 - 应保持小巧且专注 ## 8. 文件与项目结构 - `/pages` - 入口点（SSG/SSR），无客户端逻辑 - `/components` - 共享UI，岛屿位于此处 - `/layouts` - 仅静态包装器 - `/content` - Markdown / CMS 数据 - 保持 `.astro` 文件专注于组合，而非行为 ## 9. 反模式（严格禁止） - 在 `.astro` 中使用钩子 - 将 Astro 转变为 SPA 架构 - 水合整个布局/页面 - 到处使用 `client:load` - 将列表映射为水合组件 - 使用客户端JS解决静态问题 - 用客户端逻辑替代服务端逻辑 ## 10. 推荐模式 - 静态优先渲染 - 最小化、孤立的岛屿 - 懒加载水合（`visible`、`idle`） - 服务端计算 - HTML + CSS 优先于 JS - 渐进增强 ## 11. 决策框架（非常重要） 对于每个功能： 1. 这可以是静态HTML吗？ -> 是 -> 使用 `.astro` 2. 需要交互吗？ -> 否 -> 保持静态 3. 需要JS吗？ -> 是 -> 创建岛屿 4. 何时加载？ -> 选择最低优先级的 `client:*` ## 12. 心智模型（不可协商） - Astro 不是： - Next.js - SPA 框架 - React优先系统 - Astro 是： - 静态优先渲染器 - 部分水合系统 - 性能优先架构 - 思考：“发送HTML + 点缀JS”