使用 AI 工具构建 Astro 站点

AI 驱动的编辑器和智能体编码工具通常对于 Astro 的核心 API 和概念有很好的了解。然而，某些工具可能会使用旧版本的 API，并且无法了解框架的新特性或最近的更改。

这篇指南涵盖了如何使用最新的 Astro 知识增强 AI 工具，并提供了使用 AI 辅助构建 Astro 站点的最佳实践。

Astro 文档 MCP 服务器

你可以通过 Astro 文档 MCP (Model Context Protocol) 服务器确保你的 AI 工具拥有最新的 Astro 知识。这提供了对于最新文档的实时访问，帮助 AI 工具避免给出过时的建议，并确保其理解当前的最佳实践。

什么是 MCP?

模型上下文协议 (MCP) 是 AI 工具访问外部工具和数据源的一种标准化的方式。

与基于静态数据训练的 AI 不同，MCP 服务器提供了对于最新 Astro 文档的访问能力。服务器是免费且开源的，运行在远端，无需在本地安装任何内容。

Astro 文档 MCP 服务器使用 kapa.ai API 来维护 Astro 文档的最新索引。

服务器详情

• 名称: Astro Docs
• URL: https://mcp.docs.astro.build/mcp
• 传输方式: 流式（Streamable） HTTP

安装

设置流程取决于你的 AI 开发工具。你可能会看到一些工具将 MCP 服务器称为连接器（connectors）、适配器（adapters）、扩展（extensions）或插件（plugins）。

手动设置

许多工具支持通用的 JSON 配置格式来添加 MCP 服务器。如果你的工具没有特定的说明，你可能可以通过在工具的 MCP 设置中添加以下配置来添加 Astro 文档 MCP 服务器：

流式 HTTP

MCP 配置

{
  "mcpServers": {
    "Astro docs": {
      "type": "http",
      "url": "https://mcp.docs.astro.build/mcp"
    }
  }
}

本地代理

MCP 配置

{
  "mcpServers": {
    "Astro docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
    }
  }
}

Claude Code CLI

Claude Code 是一个运行在命令行中的智能体编码工具。启用 Astro 文档 MCP 服务器允许它在生成 Astro 代码时访问最新的文档。

使用终端命令安装：

claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp

在 Claude Code 中使用 MCP 服务器的更多信息

Claude Code GitHub Action

Claude Code 还提供了一个 GitHub Action，可以在响应 GitHub 事件时运行命令。启用 Astro 文档 MCP 服务器允许它在评论中回答问题或生成 Astro 代码时访问最新的文档。

你可以通过在工作流（workflow）文件中添加以下内容来配置它使用 Astro 文档 MCP 服务器访问文档：

.github/workflows/claude.yml

# ...你的其他 GitHub Action 工作流配置
- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "astro-docs": {
            "type": "http",
            "url": "https://mcp.docs.astro.build/mcp"
          }
        }
      }
    allowed_tools: "mcp__astro-docs__search_astro_docs"

在 Claude Code GitHub Action 中使用 MCP 服务器的更多信息

Codex CLI

Codex CLI 是一个命令行 AI 编码工具，可以使用 Astro 文档 MCP 服务器在生成 Astro 代码时访问最新的文档。

你可以在全局的 ~/.codex/config.toml 文件中，或在项目根目录的 .codex/config.toml 文件中配置 MCP 服务器。

~/.codex/config.toml

[mcp_servers.astro-docs]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]

在 Codex CLI 中使用 MCP 服务器的更多信息

Cursor

Cursor 是一个 AI 代码编辑器。添加 Astro 文档 MCP 服务器允许 Cursor 在执行开发任务时访问最新的 Astro 文档。

通过点击以下按钮进行安装：

添加到 Cursor

在 Cursor 中使用 MCP 服务器的更多信息

Visual Studio Code

Visual Studio Code 在使用 Copilot Chat 时支持 MCP 服务器。添加 Astro 文档 MCP 服务器允许 VS Code 在回答问题或执行编码任务时访问最新的 Astro 文档。

通过点击以下按钮进行安装：

添加到 VS Code

在 Visual Studio Code 中使用 MCP 服务器的更多信息

Warp

Warp（前身为 Warp Terminal）是一个智能体开发环境，专为使用多个 AI 智能体进行编码构建。添加 Astro 文档 MCP 服务器允许 Warp 在回答问题或执行编码任务时访问最新的 Astro 文档。

1. 打开你的 Warp 设置，前往 AI > MCP Servers > Manage MCP Servers（AI > MCP 服务器 > 管理 MCP 服务器）。
2. 点击 “Add”（添加）。
3. 输入以下配置。你可以使用 start_on_launch 标志来配置 Astro 文档 MCP 服务器在启动时激活：

   MCP Configuration

   {
     "mcpServers": {
       "Astro docs": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"],
         "env": {},
         "working_directory": null,
         "start_on_launch": true
       }
     }
   }

4. 点击 “Save”（保存）。

在 Warp 中使用 MCP 服务器的更多信息

Claude.ai / Claude Desktop

Claude.ai 是一个通用的 AI 助手。添加 Astro 文档 MCP 服务器允许 Claude.ai 在回答 Astro 问题或生成 Astro 代码时访问最新的 Astro 文档。

1. 导航至 Claude.ai 连接器设置。
2. 点击 “Add custom connector”（添加自定义连接器）。你可能需要向下滚动才能找到此选项。
3. 输入服务器 URL: https://mcp.docs.astro.build/mcp。
4. 将名称设置为 “Astro Docs”。

在 Claude.ai 中使用 MCP 服务器的更多信息

Windsurf

Windsurf 是一个 AI 驱动的智能体编码工具，可作为编辑器插件或独立编辑器使用。它可以使用 Astro 文档 MCP 服务器在执行编码任务时访问最新的 Astro 文档。

Windsurf 不支持流式 HTTP，因此它需要本地代理配置：

1. 在你的编辑器中打开 ~/.codeium/windsurf/mcp_config.json。

2. 添加以下配置到你的 Windsurf MCP 设置：

   MCP 配置

   {
     "mcpServers": {
       "Astro docs": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
       }
     }
   }

3. 保存配置并重启 Windsurf。

在 Windsurf 中使用 MCP 服务器的更多信息

Gemini CLI

Gemini CLI 是一个命令行 AI 编码工具，可以在生成 Astro 代码时使用 Astro 文档 MCP 服务器访问文档。

你可以在全局的 ~/.gemini/settings.json 文件，或项目根目录的 .gemini/settings.json 文件中配置 MCP 服务器。

.gemini/settings.json

{
  "mcpServers": {
    "Astro docs": {
      "httpUrl": "https://mcp.docs.astro.build/mcp",
    }
  }
}

在 Gemini CLI 中使用 MCP 服务器的更多信息

Google Antigravity

Google Antigravity 是一个智能体开发平台。

1. 按照连接自定义 MCP 服务器指南打开 ~/.gemini/antigravity/mcp_config.json。
2. 添加以下配置到 mcp_config.json：

   mcp_config.json

   {
     "mcpServers": {
       "astro-docs": {
         "serverUrl": "https://mcp.docs.astro.build/mcp"
       }
     }
   }

3. 保存文件并在 Manage MCPs（管理 MCP）标签页中点击 “Refresh”（刷新）。

Zed

Zed 在使用其 AI 能力时支持 MCP 服务器。它可以在执行编码任务时使用 Astro Docs MCP 服务器访问文档。

1. 在你的编辑器中打开 ~/.config/zed/settings.json。

2. 添加以下配置到你的 Zed MCP 设置：

   MCP 配置

   {
      "context_servers": {
        "Astro docs": {
          "settings": {},
          "enabled": true,
          "url": "https://mcp.docs.astro.build/mcp"
        }
      }
   }

3. 保存配置。

在 Zed 中使用 MCP 服务器的更多信息

ChatGPT

参考 OpenAI MCP 文档获取具体的安装指南。

Raycast

Raycast 可以连接 MCP 服务器以增强它的 AI 能力。添加 Astro 文档 MCP 服务器允许 Raycast 在回答问题时访问最新的 Astro 文档。

通过点击以下按钮进行安装：

添加到 Raycast

在 Raycast 中使用 MCP 服务器的更多信息

Opencode AI

Opencode AI 是一个开源的基于终端的 AI 编码工具，可以使用 Astro 文档 MCP 服务器在生成 Astro 代码时访问文档。

你可以在你的 Opencode 配置文件中配置 MCP 服务器，一般叫做 opencode.json，位于你的项目根目录或全局配置目录（例如 ~/.config/opencode/opencode.json）。

MCP 配置

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "Astro docs": {
      "type": "remote",
      "url": "https://mcp.docs.astro.build/mcp",
      "enabled": true
    }
  }
}

在 Opencode AI 中使用 MCP 服务器的更多信息

GitHub Copilot 编码智能体

GitHub Copilot 可以被用作由 GitHub Actions 驱动的编码智能体。启用 Astro 文档 MCP 服务器允许它在回答问题或执行编码任务时访问最新的 Astro 文档。

你可以在你的仓库的 Copilot 编码智能体设置中配置 MCP 服务器，这些设置可在 https://github.com/<your-org>/<your-repo>/settings/copilot/coding_agent 中找到：

MCP 配置

{
  "mcpServers": {
    "astro-docs": {
      "type": "http",
      "url": "https://mcp.docs.astro.build/mcp",
      "tools": ["mcp__astro-docs__search_astro_docs"]
    }
  }
}

了解更多 使用 MCP 服务器扩展 GitHub Copilot 编码智能体。

使用

一旦配置完成，你可以询问你的 AI 工具有关 Astro 的问题，它将直接从最新文档中检索信息。编码智能体将能够在执行编码任务时访问最新的文档，聊天机器人将能够准确回答关于 Astro 特性、API 和最佳实践的问题。

请记住

Astro 文档 MCP 服务器提供了对于最新文档的访问能力，但你的 AI 工具仍需负责解释和代码生成，AI 也会犯错，请务必仔细审查生成的代码并进行充分测试。

问题排查

如果你遇到了问题：

• 确保你的工具支持流式 HTTP 传输。
• 检查服务器 URL 是否正确：https://mcp.docs.astro.build/mcp。
• 确保你的工具具有适当的互联网访问权限。
• 查阅你工具具体的 MCP 集成文档。

如果仍然有问题，在 Astro 文档 MCP 服务器仓库提出一个 issue。

Discord AI 支持

驱动 Astro 的 MCP 服务器的相同技术也作为聊天机器人的形式存在于 Astro Discord，用于提供自助支持。访问 #support-ai 频道，使用自然语言询问有关 Astro 或你的项目的问题。你的对话会被自动创建为线程，你可以无限制地进一步提问。

与聊天机器人的对话是公开的，并且与我们的其余频道一样受到相同的服务器语言和行为规则约束，不过我们的志愿者支持成员不会主动访问这些对话。如需社区的帮助，请在我们的常规 #support 频道中创建一个线程。

后台模式

添加于： astro@7.0.0

当检测到 AI 编码智能体时，astro dev 会自动以分离的后台进程启动开发服务器。这可以防止开发服务器阻塞智能体的终端，并允许它在服务器运行时继续工作。

一个锁文件（.astro/dev.json）会在开发服务器启动时写入，记录服务器的 URL、端口和 PID。这可以防止为同一个项目启动重复的服务器。

如果你没有使用 AI 编码智能体，astro dev 会以前台进程启动，并将日志输出到终端。

要退出自动的后台模式，请在运行 astro dev 前设置 ASTRO_DEV_BACKGROUND 环境变量：

ASTRO_DEV_BACKGROUND=0 astro dev

查看 CLI 参考 以了解 astro dev 的完整标志和子命令列表。

健康检查端点

开发服务器暴露了一个 /_astro/status 端点，该端点返回 {"ok": true} 的 JSON 响应。这允许智能体和其他工具以编程方式检查开发服务器是否已准备好接受请求。该端点仅在开发服务器中可用，在生产构建中不存在。

AI 驱动的 Astro 开发的技巧

• 从模板开始：不要从零开始构建，要求 AI 工具使用现有的 Astro 模板或使用带有模板选项的 npm create astro@latest 开始。
• 使用 astro add 添加集成： 要求 AI 工具使用 astro add 添加官方集成（例如 astro add tailwind、astro add react）。对于其他的包，使用你喜欢的包管理器命令安装，而不是直接编辑 package.json。
• 确保最新的API：AI 工具可能会使用过时的模式，要求他们检查最新的文档，尤其是新的特性，例如会话（Sessions）和 Actions。对于自初次发布以来发生重大变化的特性，例如内容集合（Content Collections），或者现在可能不再处于实验性阶段的以前的实验性特性，这一点同样重要。
• 使用项目规则：如果你的 AI 工具支持，可以设置项目规则（Project Rules）来强制执行最佳实践和编码标准（例如上面列出的）。