astro-sites-manager

Astro Framework — v7

MCP 文档访问

此技能与 Astro Docs MCP 服务 协同工作。回答 Astro 问题前，请检查是否有可用的 astro-docs MCP 工具，并使用该工具查询最新文档。MCP 服务可实时访问 docs.astro.build，是当前 API 的唯一可信来源。

MCP Server: astro-docs
Tool: search_astro_docs

如果 MCP 服务不可用，请参考此技能中的参考资料和 https://docs.astro.build。

---

最佳实践

组件设计

• 每个文件只放一个 .astro 组件。组件应保持小巧、专注。
• 使用 frontmatter（---）获取数据和编写逻辑；下方模板仅用于标记。
• 除非需要客户端交互，否则优先使用 Astro 组件而不是框架组件。
• 谨慎使用 client:* 指令——每个指令都会向打包文件添加 JavaScript。
• 指令优先级：client:idle > client:visible > client:load（优先使用延迟加载）。

路由与页面

• 在 src/pages/ 中使用基于文件的路由。动态路由：[slug].astro、[...path].astro。
• 对预渲染的动态路由，始终导出 getStaticPaths()。
• 对 SSR 页面：在文件顶部设置 export const prerender = false。
• 仅当需要超出中间件所能提供的控制能力时，才使用 src/fetch.ts（v7）——不要将其用于简单身份验证。

内容集合

• 在 content.config.ts 中使用 Zod 定义架构——绝不要信任未经类型检查的内容。
• 使用 getCollection() 获取列表，使用 getEntry() 获取单个条目。
• 本地文件优先使用 glob() 加载器，CMS 数据则使用自定义加载器。

性能

• 默认使用静态渲染（prerender = true）。仅对个性化或动态内容使用 SSR。
• 使用 astro:assets 中的 <Image />——本地图片绝不要直接使用 <img>。
• Markdown 优先使用 Sätteri（v7 默认）而不是 unified——速度明显更快。
• 使用 Server Islands（server:defer）将静态外壳与动态片段组合起来。

样式

• .astro 文件中的作用域 <style> 是默认且推荐的做法。
• 仅在确有需要时使用 is:global（例如为第三方组件设置样式）。
• Tailwind：使用 astro add tailwind 安装，不要手动配置。

TypeScript

• 更改内容架构或环境变量后运行 astro sync。
• 提交前运行 astro check——它能捕获其他工具会遗漏的模板类型错误。
• 使用 astro:env/server 和 astro:env/client 定义带类型的环境变量（绝不要直接使用 process.env）。

开发工作流

• 使用 astro dev 进行 HMR。绝不要使用 python -m http.server 或其他静态服务器。
• 使用 astro add 添加官方集成——不要手动编辑配置来添加。
• 使用 astro build && astro preview 在本地测试生产环境行为。
• 在 AI Agent 工作流中：使用 astro dev --background，并通过 /_astro/status 验证。

---

CLI 命令

npx astro dev              # Dev server (foreground)
npx astro dev --background # Dev server (detached, for AI agents)
npx astro dev --json       # Dev server with JSON structured logs
npx astro build            # Production build
npx astro preview          # Serve production build locally
npx astro check            # Type checking and diagnostics
npx astro sync             # Generate TypeScript types
npx astro add <integration># Install and configure integration

后台开发服务器（AI Agent）

作为 AI Agent 工作时，请使用后台模式：

# Start (blocks until ready, then detaches)
astro dev --background
# → Dev server running at http://localhost:4321 (pid 12345)

# Check status
astro dev status

# Read logs
astro dev logs

# Stop
astro dev stop

# Health check endpoint (JSON)
curl http://localhost:4321/_astro/status
# → {"ok": true}

主要行为：

• 锁文件可防止启动重复实例——再次启动时会返回现有实例
• 所有命令均为幂等操作（停止未运行的服务时会静默成功）
• 在 AI Agent 中运行时会自动检测（无需标志）
• 退出后台模式：ASTRO_DEV_BACKGROUND=0 astro dev

---

项目结构

src/
├── pages/          # File-based routing (.astro, .md, .mdx)
├── layouts/        # Reusable page layouts
├── components/     # Astro & framework components
├── content/        # Content collections (type-safe)
├── middleware.ts   # Request middleware
├── fetch.ts        # Advanced routing (v7, optional)
├── styles/         # Global CSS
├── assets/         # Optimized assets (images, fonts)
├── actions/        # Server actions
└── env.d.ts        # Environment type declarations
astro.config.mjs    # Main configuration
content.config.ts   # Content collection schemas
tsconfig.json       # TypeScript config

---

配置（v7）

import { defineConfig, memoryCache, logHandlers } from 'astro/config';

export default defineConfig({
  // Output mode
  output: 'static', // or configure per-page with server adapter

  // Route caching (stable in v7)
  cache: {
    provider: memoryCache(),
  },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },

  // Logger (stable in v7)
  logger: logHandlers.json(), // or .console(), or .compose(...)

  // Markdown (Sätteri is default in v7)
  markdown: {
    // No config needed for defaults (GFM, smartypants, heading IDs)
    // For extra features:
    // processor: satteri({ features: { directive: true, math: true } })
  },

  // Advanced routing file (default: src/fetch.ts)
  // fetchFile: null, // disable if src/fetch.ts is used for other purposes

  // Whitespace (v7 default: 'jsx')
  compressHTML: 'jsx', // or true (v6 behavior), or false (preserve all)
});

---

Islands 架构（client:* 指令）

<Counter client:load />


<Newsletter client:idle />


<Comments client:visible />


<MobileMenu client:media="(max-width: 768px)" />


<MapWidget client:only="react" />


<UserGreeting server:defer />

决策指南： 不添加指令（默认）= 不生成 JavaScript，使用静态 HTML。仅在需要用户交互时添加指令。

---

图片优化

---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';
---

<Image src={heroImage} alt="Hero" width={1200} />


<Image src="https://cdn.example.com/photo.jpg" alt="Photo" width={800} height={600} />

远程图片配置：

// astro.config.mjs
image: {
  domains: ['cdn.example.com'],
  remotePatterns: [{ protocol: 'https', hostname: '**.cloudinary.com' }],
}

---

详细参考

• 安装 MCP 服务 — 为任何 AI 工具（Kiro、Claude、Cursor、VS Code 等）设置 Astro Docs MCP
• v6→v7 迁移指南 — 逐步升级计划及破坏性变更检查清单
• 验证清单 — 验证安装并检测破坏性／已弃用模式
• AI 开发服务器 — 后台模式、JSON 日志记录、Agent 检测
• Astro v7 功能 — Rust 编译器、Sätteri、高级路由、路由缓存、CDN 提供商
• Astro v6 功能 — Content Collections v2、Actions、Sessions、Server Islands、env 模块
• 相关内容 — 为相关帖子生成向量嵌入，无模型地轻量部署到 Coolify
• 测试 — Vitest 组件、Playwright E2E、链接检查、CI 流水线
• SEO 全栈 — JSON-LD 图谱、Agent 发现、IndexNow、OG 图片、构建时验证、性能
• Starlight 与模式 — 文档站点、Pagefind 搜索、国际化、分页、RSS
• 部署 — Cloudflare、Vercel、Netlify、Firebase、GitHub Pages、Docker/Coolify、Azure
• Coolify 部署 — 在 Coolify 上可自托管部署（Dockerfile、API、注意事项、推荐技术栈）