要点

本篇是 Astro 的条目式速查，按用途分七组：CLI 命令、配置项、内容集合 API（astro:content）、Astro 全局对象、模板指令、脚本与样式处理、环境变量；文末有全量速查表，可只搜表定位条目。版本基线为 Astro 5.2.x 稳定线（截至 2025-02-22），仅在基线成立的行为单独标注。机制讲解不在本篇重复：指令与注水细节见《Astro 语法要点：组件、指令与客户端脚本》，工程从零跑通的步骤见《第一个 Astro 应用》。

CLI 命令组

命令都通过 npx astro 或 package.json scripts 调用。组内共性：dev 与 build 会自动先执行 sync；preview 只碰构建产物，不碰源码。

astro sync：类型从哪来

npx astro sync   # dev/build 自动执行；手动跑主要为编辑器类型提示与 CI 诊断

一句话语义：内容集合和 astro:env 的 TypeScript 类型是按你的 schema 现生成的，sync 负责生成它们。⚠️ 常见坑：新增集合后编辑器不认 getCollection('新集合') 的参数，多半是类型没刷新——跑一次 sync 或重启 dev server。

astro add：集成的正确装法

npx astro add react      # UI 框架：react / vue / svelte / solid / preact / alpine / lit
npx astro add mdx tailwind node   # 集成与 adapter 可以一条命令装多个

一句话语义：装包 + 写进 astro.config.mjs 的 integrations/adapter，一步到位。⚠️ 常见坑：装 adapter 前先想清部署平台——adapter 决定运行环境（Node 还是边缘），选错要连代码一起改。

配置组：astro.config.mjs

最小可用配置

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://docs.example.com',  // 影响 sitemap 与 canonical
  // output: 'static' 是默认值；要 SSR 时才显式写 'server' 并配 adapter
});

⚠️ 常见坑：output: 'server' 加了 adapter 之后，默认全部路由变按需渲染——想保持”文档主体静态、个别页面动态”，要在页面里用 export const prerender = true 逐个标回来，而不是整站跟着 adapter 走。

内容集合组：astro:content

定义集合（schema 用 Zod 3）

// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { blog };

⚠️ 常见坑：Astro 5 的 astro:content 导出的 z 是 Zod 3——collections 的 schema 一律从这里拿，别在项目里再单独装一份 zod 混用，两份 Zod 的校验行为与类型推导可能对不上。

查询与渲染（动态路由全套）

---
// src/pages/blog/[...id].astro
import { getCollection, render } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog', ({ data }) => !data.draft);
  return posts.map((entry) => ({ params: { id: entry.id }, props: { entry } }));
}

const { entry } = Astro.props;
const { Content } = await render(entry);
---
<article>
  <h1>{entry.data.title}</h1>
  <Content />
</article>

⚠️ 常见坑：getCollection 的过滤器在数据量大时值得写——draft、语言、分区过滤都放这里，别取全量再在页面里筛。

Astro 全局对象组

params 与 cookies 的最小示例

// Astro.params：静态模式必须由 getStaticPaths 提供 params（见内容集合组示例）
const { id } = Astro.params;

// Astro.cookies：server 输出下读写
const theme = Astro.cookies.get('theme')?.value ?? 'light';
Astro.cookies.set('theme', 'dark', { path: '/' });

⚠️ 常见坑：把 Astro.cookies/Astro.redirect 写进纯静态站，构建不报错但行为不是你想要的——静态页构建期就定稿，没有”每个请求”可言。这两个 API 出现在代码里，就是该考虑 server 输出的信号。

模板指令组

机制与选型见语法要点篇，这里只留速查。

脚本与样式处理组

<style define:vars={{ accent: 'rebeccapurple' }}>
  .btn { background: var(--accent); }   /* define:vars 序列化为 CSS 变量 */
</style>

⚠️ 常见坑：给页面里的 React 岛写 scoped 样式——data-astro-cid 属性只加在 .astro 模板的元素上，岛内部命中不了；岛内样式归岛自己（CSS Modules、内联都行），或经 props 传 class。与React 渲染边界同理：边界内外各管各的。

环境变量组

// astro.config.mjs —— 声明 schema
import { defineConfig, envField } from 'astro/config';

export default defineConfig({
  env: {
    schema: {
      API_BASE: { type: 'string', context: 'client', access: 'public' },
      SEARCH_KEY: { type: 'string', context: 'server', access: 'secret' },
    },
  },
});

// 使用：按 context 从对应入口导入
import { API_BASE } from 'astro:env/client';
import { SEARCH_KEY, getSecret } from 'astro:env/server';

const key = SEARCH_KEY ?? (await getSecret('SEARCH_KEY'));  // secret 走 getSecret 运行时读

⚠️ 常见坑：两套机制混着用时最容易犯的错是把秘密放 import.meta.env——它在构建时硬编码，产物里 grep 就能拿到。原则：给浏览器的公开值走 client；只在服务端用的走 server secret；纯静态站需要”运行时才知的秘密”，说明该给那一个路由开 server 输出。

速查表

延伸阅读

指令机制、脚本管线与注水决策的完整讲解见Astro 语法要点；这些 API 组合成真实项目的全过程见用 Astro 做一个极速文档站；按阶段串起本系列与相关文章的路径见Astro 学习路线；最基础的三件套（页面、组件、岛）回第一个 Astro 应用。

版本核实（2025-02-22 撰写时检索）：本篇基线为 Astro 5.2.x 稳定线（GitHub releases 口径）。Content Layer API（content.config.ts、glob() loader、getCollection/getEntry/render(entry)、entry.id）为 Astro 5.0 引入的现行 API，legacy 集合（type: 'content'）已弃用；astro:content 导出 Zod 3，collections schema 用它；Node 基线为 18.17+ / 20+；astro:env 自 Astro 5.0 稳定；client:* 五条指令、模板指令（class:list、set:html、set:text、is:inline、is:global、is:raw、define:vars）、脚本默认处理管线、data-astro-rerun、transition:* 均为官方指令参考现行内容。安装命令不钉版本号，以 docs.astro.build 为准。