使用 Astro 开发静态优先、部分水合网站时的完整实践

适用于用 Astro 构建静态生成、最小 JavaScript、可集成多框架组件的高性能网站。

适用场景

解决思路

1. 编写简洁、技术性的回答，并提供准确的 Astro 示例。
2. 利用 Astro 的部分水合（partial hydration）和多框架支持。
3. 优先静态生成并最小化 JavaScript，以提升性能。
4. 使用描述性变量名，并遵循 Astro 约定。
5. 按 Astro 的基于文件的路由组织文件。
6. 按以下目录组织项目：`src/components/`、`src/layouts/`、`src/pages/`、`src/styles/`、`public/`、`astro.config.mjs`。
7. 为组件创建 `.astro` 文件。
8. 必要时使用框架特定组件（React、Vue、Svelte）。
9. 实现正确的组合与可复用性。
10. 通过 Astro 的组件 props 传递数据。
11. 在 `src/pages/` 中使用基于文件的路由。
12. 使用 `[...slug].astro` 实现动态路由。
13. 使用 `getStaticPaths()` 进行静态页面生成。
14. 创建 `404.astro` 处理错误。
15. 最小化客户端 JavaScript。
16. 策略性使用 `client:*` 指令。
17. 对需要立即交互的组件使用 `client:load`。
18. 对非关键功能使用 `client:idle`。
19. 对进入视口触发水合的组件使用 `client:visible`。
20. 为资源实现懒加载。
21. 利用内置资源优化。
22. 使用 Markdown（`.md`）或 MDX（`.mdx`）文件。
23. 利用 frontmatter 支持。
24. 实现内容集合（content collections）。
25. 在 `.astro` 文件中使用作用域 `<style>` 标签。
26. 在布局中导入全局样式。
27. 通过 `@astrojs/tailwind` 集成 Tailwind。
28. 大量使用工具类（utility classes）。
29. 使用 `Astro.props` 获取组件数据。
30. 使用 `getStaticPaths()` 进行构建时数据获取。
31. 使用 `Astro.glob()` 获取本地文件。
32. 实现正确的错误处理。
33. 使用 Astro 的 `<head>` 标签设置元数据。
34. 实现 canonical URL。
35. 使用语义化 HTML。
36. 实现 ARIA 属性。
37. 确保键盘导航。
38. 优先关注 Core Web Vitals（LCP、FID、CLS）。
39. 使用 Lighthouse 和 WebPageTest。
40. 监控性能预算。

适用边界 · 注意事项

• 不适合以大量客户端交互、复杂全局状态和 SPA 路由为主的项目。
• 当项目必须使用非 Astro 的框架、托管或构建体系，且无法引入 Astro 时。
• 如果只需要纯服务端动态应用且不关心静态生成与最小 JavaScript，Astro 的静态优先模式收益有限。