astro

Astro 使用指南

代码示例和最新 API 请始终查阅 docs.astro.build。

Astro 是面向内容驱动型网站的 Web 框架。

---

快速参考

文件位置

CLI 会在 ./ 中查找 astro.config.js、astro.config.mjs、astro.config.cjs 和 astro.config.ts。自定义路径请使用 --config。

CLI 命令

• npx astro dev - 启动开发服务。
• npx astro build - 构建项目并将其写入磁盘。
• npx astro check - 检查项目中的错误。
• npx astro add - 添加集成。
• npx astro sync - 为所有 Astro 模块生成 TypeScript 类型。

添加或更改插件后，请重新运行。

项目结构

请参阅项目结构文档。

• src/* - 项目源代码（组件、页面、样式、图像等）
• src/pages - 必需。 定义所有页面和路由。
• src/components - 组件（惯例目录，并非必需）。
• src/layouts - 布局组件（惯例目录，并非必需）。
• src/styles - CSS/Sass 文件（惯例目录，并非必需）。
• public/* - 非代码、未经处理的资源（字体、图标等）；会原样复制到构建输出中。
• package.json - 项目清单。
• astro.config.{js,mjs,cjs,ts} - Astro 配置文件。（推荐）
• tsconfig.json - TypeScript 配置文件。（推荐）

---

核心配置选项

选项	说明
site	最终部署的网址。用于生成站点地图和规范 URL。

astro.config.ts 示例

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
});

---

常见工作流

创建基本页面

在 src/pages/ 中添加文件——文件名将成为路由：

---
// src/pages/index.astro
const title = 'Hello, Astro!';
---
<html>
  <head><title>{title}</title></head>
  <body>
    <h1>{title}</h1>
  </body>
</html>

创建组件

---
// src/components/Card.astro
const { title, body } = Astro.props;
---
<div class="card">
  <h2>{title}</h2>
  <p>{body}</p>
</div>

使用适配器部署

1. 添加适配器：npx astro add vercel --yes（或 node、cloudflare、netlify）
2. 运行 npx astro check，在构建前检查类型和配置错误。
3. 运行 npx astro build，生成部署产物。
4. 继续操作前，请确认构建输出目录（例如 dist/）存在且非空。
5. 根据适配器文档部署输出内容。

---

适配器

使用构建适配器，将项目部署到你喜爱的服务器、无服务器平台或边缘托管平台。使用适配器可在 Astro 项目中启用按需渲染。

使用 astro add 添加 Node.js 适配器：

npx astro add node --yes

使用 astro add 添加 Cloudflare 适配器：

npx astro add cloudflare --yes

使用 astro add 添加 Netlify 适配器：

npx astro add netlify --yes

使用 astro add 添加 Vercel 适配器：

npx astro add vercel --yes

其他社区适配器

资源

• 文档
• 配置参考
• llms.txt
• GitHub