数据获取与 SSR 模式

在 Frontmatter 中获取数据

静态模式的数据获取

Astro 默认以静态生成（SSG）模式工作——构建时执行 frontmatter 代码，生成静态 HTML。这意味着你可以在 frontmatter 中直接调用任何 Node.js API，包括文件系统、数据库驱动等。

---
// 构建时执行，可以调用任何 Node.js API
import fs from 'node:fs/promises';
import { db } from '../lib/db';

// fetch API（Node 18+ 内置）
const response = await fetch('https://api.github.com/repos/withastro/astro');
const repo = await response.json();

// 读取本地文件
const config = JSON.parse(await fs.readFile('./config.json', 'utf-8'));

// 查询数据库（构建时）
const featuredPosts = await db.post.findMany({
  where: { featured: true },
  take: 3,
});
---

<h1>GitHub Stars: {repo.stargazers_count}</h1>
<ul>
  {featuredPosts.map(p => <li>{p.title}</li>)}
</ul>

启用 SSR：服务端渲染模式

安装适配器

# Vercel（推荐）
npx astro add vercel

# Netlify
npx astro add netlify

# Node.js 自托管
npx astro add node

# Cloudflare Workers/Pages
npx astro add cloudflare

// astro.config.mjs - SSR 配置
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',    // 全站 SSR
  adapter: vercel(),
});

// 或者混合模式：默认 SSG，个别页面启用 SSR
export default defineConfig({
  output: 'hybrid',    // 混合模式（Astro 2.6+）
  adapter: vercel(),
});

SSR 页面中的请求对象

---
// 在 output: 'server' 或 output: 'hybrid' + export const prerender = false 时
export const prerender = false;  // 混合模式时明确声明此页面为 SSR

// Astro.request：当前请求的 Request 对象
const url = new URL(Astro.request.url);
const searchQuery = url.searchParams.get('q') ?? '';

// 读取请求头
const userAgent = Astro.request.headers.get('user-agent');

// 读取 Cookie
const cookie = Astro.cookies.get('session');
const sessionId = cookie?.value;

// 读取 POST 请求 body
if (Astro.request.method === 'POST') {
  const formData = await Astro.request.formData();
  const username = formData.get('username');
}

// 设置响应头
Astro.response.headers.set('Cache-Control', 'private, max-age=0');
---

<p>搜索：{searchQuery}</p>

API 路由

创建 API 端点

// src/pages/api/users.ts
import type { APIRoute } from 'astro';
import { db } from '../../lib/db';

export const GET: APIRoute = async ({ request, params }) => {
  const users = await db.user.findMany();
  return new Response(JSON.stringify(users), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
};

export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();
  const user = await db.user.create({ data: body });
  return new Response(JSON.stringify(user), { status: 201 });
};

环境变量

# .env 文件
DATABASE_URL=postgresql://localhost/mydb
API_SECRET=your-secret-key-here

# PUBLIC_ 前缀的变量可在客户端访问
PUBLIC_API_BASE_URL=https://api.example.com

---
// 服务端（frontmatter）可访问所有环境变量
const dbUrl = import.meta.env.DATABASE_URL;
const secret = import.meta.env.API_SECRET;

// PUBLIC_ 前缀的变量在客户端也可访问
const apiBase = import.meta.env.PUBLIC_API_BASE_URL;
---

SSG vs SSR 的核心区别

Astro.locals：SSR 中间件通信

// src/middleware.ts（Astro 中间件）
import { defineMiddleware } from 'astro:middleware';
import { verifyJWT } from './lib/auth';

// 中间件在每个请求时运行，可以向 locals 注入数据
export const onRequest = defineMiddleware(async (context, next) => {
  const token = context.cookies.get('session')?.value;

  if (token) {
    const user = await verifyJWT(token);
    // 将用户信息注入到 locals，所有 Astro 页面/API 都能访问
    context.locals.user = user;
  }

  // 保护路由：未登录则重定向
  if (context.url.pathname.startsWith('/dashboard') && !context.locals.user) {
    return context.redirect('/login');
  }

  return next();
});

// 在页面中使用 locals
// const { user } = Astro.locals;

Astro Actions：类型安全的服务端函数

Astro Actions（Astro 5 稳定版特性）是一种在服务端定义、在客户端调用的 RPC 机制。不同于传统 API 路由，Actions 提供全链路 TypeScript 类型安全：输入参数由 zod 验证，返回值类型自动推断，客户端调用无需手写 fetch 代码。

定义 Actions

// src/actions/index.ts
import { defineAction, ActionError } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  // 发送联系表单的 Action
  contact: defineAction({
    // input 使用 zod 验证，自动生成 TypeScript 类型
    input: z.object({
      name: z.string().min(1, '姓名不能为空'),
      email: z.string().email('邮箱格式不正确'),
      message: z.string().min(10, '消息至少 10 个字符'),
    }),
    // handler 在服务端执行，可访问数据库、发送邮件等
    handler: async ({ name, email, message }) => {
      const result = await db.contact.create({
        data: { name, email, message, createdAt: new Date() }
      });
      // 发送通知邮件
      await sendEmail({ to: 'admin@example.com', subject: `新留言来自 ${name}` });
      return { id: result.id, success: true };
    },
  }),

  // 需要认证的 Action
  updateProfile: defineAction({
    input: z.object({
      displayName: z.string().optional(),
      bio: z.string().max(200).optional(),
    }),
    handler: async (input, context) => {
      // context 包含 request、cookies、locals（中间件注入的数据）
      const user = context.locals.user;
      if (!user) {
        throw new ActionError({
          code: 'UNAUTHORIZED',
          message: '请先登录',
        });
      }
      return db.user.update({ where: { id: user.id }, data: input });
    },
  }),
};

在客户端调用 Actions

---
// src/pages/contact.astro
import { actions } from 'astro:actions';
---

<form>
  <input name="name" placeholder="姓名" required />
  <input name="email" type="email" placeholder="邮箱" required />
  <textarea name="message" placeholder="留言"></textarea>
  <button type="submit">发送</button>
</form>

<script>
import { actions } from 'astro:actions';

document.querySelector('form')?.addEventListener('submit', async (e) => {
  e.preventDefault();
  const formData = new FormData(e.target as HTMLFormElement);

  // 类型安全调用：参数类型由 zod schema 推断，返回值类型自动推断
  const { data, error } = await actions.contact(formData);

  if (error) {
    // error.code 是字符串枚举（BAD_REQUEST / UNAUTHORIZED 等）
    console.error(error.message);
    return;
  }

  // data 类型完全推断自 handler 返回值
  console.log(`提交成功，ID: ${data.id}`);
});
</script>

本章小结