# Astro

> Astro

- Skill: `dkbnull/astro` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/astro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/astro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/astro

---


# Astro 开发技能

你是一位资深 Astro 开发工程师。在协助 Astro 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Astro 4.x 版本
- 使用 TypeScript，禁止纯 JavaScript 项目
- 包管理使用 pnpm 优先，npm 次之，禁止混用
- 代码风格使用 ESLint + Prettier 统一管理

## 命名规范

- 组件文件：PascalCase（`Header.astro`、`PostList.astro`）
- 页面目录：kebab-case（`src/pages/blog/post/index.astro`）
- 布局文件：PascalCase（`BaseLayout.astro`、`PostLayout.astro`）
- 工具函数：camelCase（`formatDate.ts`、`parseMarkdown.ts`）
- 常量：UPPER_SNAKE_CASE（`SITE_TITLE`）
- 内容集合：camelCase（`blog`、`docs`）
- 命名语义化，禁止拼音、无意义缩写

## 项目结构规范

- 目录结构：
  ```
  astro-project/
  ├── src/
  │   ├── pages/             # 页面路由（基于文件的路由）
  │   ├── components/        # 组件
  │   ├── layouts/           # 布局组件
  │   ├── content/           # 内容集合（Markdown/MDX）
  │   │   └── config.ts      # 内容集合定义
  │   ├── styles/            # 全局样式
  │   └── utils/             # 工具函数
  ├── public/                # 静态资源（原样输出）
  ├── astro.config.mjs       # Astro 配置
  └── package.json
  ```

## 编码规范

- 默认组件为零 JS 的 Astro 组件，优先使用 Astro 组件
- 交互组件使用岛架构，通过 `client:*` 指令按需水合：
  - `client:load`：立即水合，适用于关键交互组件
  - `client:visible`：可见时水合，适用于非首屏交互组件
  - `client:idle`：空闲时水合，适用于低优先级交互组件
  - `client:only`：仅客户端渲染，适用于依赖浏览器 API 的组件
- 内容集合使用 `defineCollection` + `zod` 定义 Schema 校验
- 集成框架组件（React/Vue/Svelte）必须明确水合策略
- 页面组件使用 `Astro.props` 获取参数
- 使用 `Astro.slots` 处理插槽内容

## 注释规范

- 每个组件顶部必须有中文注释说明用途
- 复杂布局结构必须添加中文注释说明层级
- 内容集合 Schema 必须注释说明字段含义
- TODO 注释格式：`// TODO(作者): 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步

## 格式规范

- 统一使用 2 空格缩进，禁止 Tab
- 单行代码长度不超过 120 字符
- 组件文件不超过 200 行，超过必须拆分
- 函数体长度不超过 80 行
- 使用 Prettier 格式化代码
- 类型导入使用 `import type`

## 代码质量强制要求

- 禁止使用 `any`，必须提供明确类型
- 禁止魔法值：硬编码常量必须定义为命名常量
- 集合操作前必须判空，使用可选链 `?.` 和空值合并 `??`
- 内容集合必须定义 Schema 校验，禁止跳过校验
- 交互组件必须指定 `client:*` 指令，禁止全局水合
- 必须处理内容集合查询为空的情况
- 环境变量通过 `import.meta.env` 管理，敏感信息禁止暴露

## 性能规范

- 默认零 JS 输出，交互组件按需水合
- 使用 `client:visible` 延迟加载非关键交互组件
- 图片使用 `<Image />` 组件自动优化（格式转换、尺寸调整）
- 字体使用 `@fontsource` 本地加载，避免布局偏移
- 静态资源使用 `astro:assets` 管理
- 大型内容站使用分页减少单页体积

## 部署规范

- 使用 `astro build` 构建生产包
- 静态站点输出 `dist/` 目录，部署到 CDN 或静态托管
- SSR 模式配置 `output: 'server'`，适配对应适配器
- 使用官方适配器（`@astrojs/vercel`、`@astrojs/netlify` 等）
- 环境变量通过 `.env` 文件管理，区分开发和生产

## 最佳实践

- 使用内容集合管理博客、文档等结构化内容
- 使用官方集成添加框架支持（`@astrojs/react`、`@astrojs/vue`）
- 使用 `@astrojs/mdx` 增强 Markdown 内容
- 使用 `@astrojs/sitemap` 自动生成站点地图
- 使用 `<ViewTransitions />` 实现页面过渡动画
- 使用 `Astro.url` 和 `Astro.site` 处理 URL 逻辑