astro-best-practices

Astro 最佳实践

在设计、实现或审查 Astro 项目时，请将此技能作为基准。它将 Astro 特定的架构指导转化为可移植的说明，可应用于不同 Agent。

核心原则

• 如果不需要在请求时渲染，优先采用静态生成
• 尽量减少客户端 JavaScript
• 仅在确实需要交互时使用框架岛屿
• 保持清晰的项目结构和可预测的路由
• 不要只追求输出一致性，还要优化无障碍性和可维护性

架构默认做法

优先使用 .astro

• 对于静态和大部分静态的 UI，使用 .astro 组件
• 只有在确实需要局部状态或客户端行为时，才使用 React、Vue 或其他框架
• 让交互岛屿保持小巧，并尽量作为叶节点

有意识地使用水合

• client:visible 用于延迟加载的 UI
• client:idle 用于优先级较低的增强功能
• client:load 仅用于需要立即交互的关键功能
• 只有在有意跳过服务器端渲染时，才使用 client:only

默认不要对大范围布局区域进行水合。

保持项目结构清晰可预测

典型结构：

src/
  components/
  layouts/
  pages/
  content/
  styles/
  assets/
public/

除非有明确的项目特定原因，否则不要另创目录结构。

内容和数据

• 对结构化内容使用内容集合
• 定义架构，而不是接受格式松散的 frontmatter
• 除非有明确理由，否则在 Astro frontmatter 中获取服务器端数据
• 让数据流清晰易懂，并靠近负责它的组件或页面

无障碍性

• 使用语义化地标，例如 header、nav、main、article 和 footer
• 确保所有交互控件都可通过键盘操作
• 提供有意义的标签和无障碍名称
• 保持正确的标题层级
• 使用恰当的图像替代文本
• 保留可见的焦点状态
• 将色彩对比度视为不可妥协的基础要求

性能

• 有意识地使用 astro:assets 或项目选定的图像处理流程
• 通过提供图像尺寸或稳定的容器来防止布局偏移
• 避免不必要的客户端水合
• 将 CSS 和 JavaScript 限定在需要它们的功能范围内
• 优先采用简单的服务器渲染标记，而不是增加客户端复杂性

样式

• 默认使用作用域限定的组件样式，除非项目已有明确的样式系统
• 使用 CSS 自定义属性定义可复用的设计令牌
• 如果项目并非已采用工具优先的方式，则优先选择易于维护的布局模式，避免零散的一次性工具类
• 让响应式行为经过有意设计且可测试

审查清单

完成 Astro 项目工作前，请检查：

• 是否存在不必要的水合代码
• HTML 是否保持语义化
• 路由和布局结构是否依然清晰
• 内容架构是否足够完善
• 结果是否便于使用键盘和辅助技术访问
• 实现是否符合现有项目规范