遵循 Astro 的「HTML 优先 / 默认零 JavaScript」原则：

• 除非明确需要交互，否则一切都是静态 HTML。
• JavaScript 是一种成本 → 只有在能创造真实用户价值时才添加。

始终以「岛屿架构」思考：

• 页面是静态 HTML
• 交互部分是被隔离的岛屿
• 绝不把整个页面当作一个应用

在编写任何 JavaScript 之前，始终先问： 「这能否用 HTML + CSS 或服务端逻辑解决？」

使用 .astro 组件来处理：

• 布局
• 组合
• 静态 UI
• 数据获取
• 服务端逻辑（frontmatter）

.astro 组件：

• 在构建时或服务端运行
• 默认不发送 JavaScript
• 必须保持框架无关

绝不在 .astro 中使用 React/Vue/Svelte 钩子

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

将每个交互组件视为一个隔离的岛屿：

• 独立
• 自包含
• 范围最小

绝不：

• 水合整个页面或布局
• 将大型组件树包裹在单个岛屿中
• 在循环中不必要地创建许多小岛屿

优先：

• 静态列表渲染
• 仅水合最小的交互单元

始终使用 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 frontmatter 内）：

• 数据获取
• 转换
• 过滤 / 排序
• 派生值

仅在以下情况使用客户端状态：

• 用户交互需要它
• 需要实时更新

避免：

• 在客户端重复逻辑
• 将服务端逻辑移入孤岛

除非绝对必要，避免使用客户端状态。

如果需要：

• 仅将状态限定在孤岛内部
• 除非有要求，绝不创建全局应用状态

对于跨孤岛状态：

• 使用轻量级共享存储（例如 nano stores）
• 默认避免使用重量级全局状态系统

最小化发送到客户端的 JavaScript：

• Astro 仅为已水合的组件加载 JS :contentReference[oaicite:1]{index=1}

优先使用：

• 静态渲染
• 部分水合
• 惰性水合

避免：

• 水合大型列表
• 在循环中重复使用孤岛
• 过度使用 client:load

每个孤岛：

• 有自己的 bundle
• 独立加载
• 应保持小而专注 :contentReference[oaicite:2]{index=2}

/pages

• 入口点（SSG/SSR）
• 无客户端逻辑

/components

• 共享 UI
• 孤岛位于此处

/layouts

• 仅静态包装器

/content

• Markdown / CMS 数据

让 .astro 文件专注于组合，而非行为

Astro 不是：

• Next.js
• SPA 框架
• React 优先的系统

Astro 是：

• 静态优先渲染器
• 部分水合系统
• 性能优先的架构

思考方式： ❌ “构建一个应用” ✅ “交付 HTML + 撒点 JS”

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?"

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

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

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

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

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

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}

/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

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”