实验性 sessions

类型： SessionConfig
默认值： undefined

添加于： astro@5.1.0

会话（session）是用于存储按需渲染页面在请求间的用户状态。

该实验性功能允许你存储和读取诸如登录状态、购物车内容、或者是其他用户特定数据：

---
export const prerender = false; // 在 'server' 模式下不需要
const cart = await Astro.session.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

会话依赖于一个可配置的会话 driver 来将数据存储在 session 对象上。一个会话 cookie 存储一个识别会话 ID。

session 对象允许你和存储的用户状态（例如：添加物品至购物车）和会话 ID（例如：当退出登录时删除会话 ID）进行交互。

启用实验性 sessions

目前位于 experimental.sessions 的早期版本中，Astro 的官方服务器适配器还尚未更新以提供基于平台默认存储功能的默认会话驱动。在这些驱动内置之前，除了添加适配器之外，你还必须在 experimental.sessions 配置对象中自己指定 driver。

接下来的部分展示了每个适配器的推荐驱动。（这些驱动将在此功能的稳定版本中自动为你配置。）或者，你也可以指定 unstorage 上任何支持的驱动。

使用 Node 适配器来配置会话

Node 适配器与文件系统驱动相兼容。请注意，该方式无法在无服务器环境中使用，因为它们没有共享文件系统。

  {
    adapter: node({ mode: 'standalone' }),
    experimental: {
      session: {
        // 必需：unstorage 上的驱动名称
        driver: "fs",
      },
    },
  }

为其他适配器配置会话驱动

选择与你的托管平台提供的存储功能相对应的 unstorage driver 名称，例如 Netlify Blobs 驱动（netlify-blobs）、Cloudflare KV 驱动（cloudflare-kv-binding）或 Deno KV 驱动程序（deno-kv）。你还可以使用跨平台驱动，例如 Upstash 或 Redis。

驱动选项

你还可以将 session.options 单独以对象的形式将任意的可用选项传入 unstorage。以下示例配置了 Netlify Blobs 驱动，同时还提供了 name 并指定为 consistency 模式：

  {
    adapter: netlify(),
    experimental: {
      session: {
        // unstorage 驱动的名称遵循烤串命名法
        driver: "netlify-blobs",
        options: {
          name: 'astro-sessions',
          // 会话需要强一致性
          consistency: 'strong',
        }
      },
    },
  }

使用会话

配置好驱动后，你就可以使用 session 对象与会话进行交互了。该对象可作为 Astro.session 从 Astro 组件和页面中以及 API 端点、中间件和 action 中的 context 对象上被读取到。所有情况下的 API 都是相同的。

在大多数情况下，你只需使用 Astro.session.get() 和 Astro.session.set()。有关其他可用方法，请参阅 API 部分。

Astro 组件和页面

在 .astro 组件和页面中，你可以通过全局 Astro 对象读取到会话对象。例如，要显示购物车中的商品数量：

---
export const prerender = false; // 在 'server' 模式下不需要
const cart = await Astro.session.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

API 端点

在 API 端点中，会话对象在 context 对象中可用。例如，要向购物车中添加一件商品：

import type { APIContext } from "astro";

export async function POST(req: Request, context: APIContext) {
  const cart = await context.session.get("cart");
  cart.push(req.body.item);
  await context.session.set("cart", cart);
  return Response.json(cart);
}

Actions

在 action 中，会话对象在 context 对象中可用。例如，要向购物车中添加一件商品：

import { defineAction } from "astro:actions";
import { z } from "astro:schema";

export const server = {
  addToCart: defineAction({
    input: z.object({ productId: z.string() }),
    handler: async (input, context) => {
      const cart = await context.session.get("cart");
      cart.push(input.productId);
      await context.session.set("cart", cart);
      return cart;
    },
  }),
};

中间件

在中间件中，会话对象在 context 对象中可用。例如，在会话中设置最后访问的时间：

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  context.session.set('lastVisit', new Date());
  return next();
});

Cookies

首次访问时会生成会话，并在响应中设置一个会话 ID cookie。Cookie 中不存储实际的用户数据，仅存储用于识别用户会话的 ID。会话可以随时使用 Astro.session.regenerate() 重新生成，或使用 Astro.session.destroy() 销毁。

`session.cookie`

类型： string | object
默认值： undefined

一个用于设置 cookie 选项的可选属性。可以通过提供一个字符串来自动设置 cookie.name 属性。要配置其他选项，请提供一个对象。

  {
    experimental: {
      session: {
        // 如果设置为一个字符串，则会将其用作 cookie name
        // cookie: "my-session-id",
        // 如果设置为一个对象，则允许配置高级选项
        cookie: {
          name: "my-session-id"
          sameSite: "Strict",
        },
      }
    }
  }

会话 API

会话对象在所有 Astro 上下文中都可用，包括组件、action 和 API 端点。在组件中，它是通过全局 Astro 对象来读取到的，在 action 和 API 端点中，它在 context 对象中可用。所有情况下的 API 都是相同的。

使用 devalue 对值进行序列化和反序列化，该库与 content layer 和 action 使用的库相同。这意味着支持的类型是相同的，包括字符串、数字、Date、Map、Set、URL、数组和简单对象。

`session.get()`

类型： (key: string) => Promise<any>

返回会话中给定键的值。如果该键不存在，则返回 undefined。

`session.set()`

类型： (key: string, value: any, options?: { ttl: number }) => void

设置会话中给定键的值。该值可以是任何可序列化类型。

`session.regenerate()`

类型： () => void

重新生成会话 ID。最佳实践是在用户登录或升级权限时调用此方法，以防止会话固定攻击。

`session.destroy()`

类型： () => void

销毁会话，从后端删除 cookie 和对象。当用户退出登录或会话无效时应调用此方法。

延伸阅读

有关此实验性 API 的完整详细信息和反馈，请参阅会话 RFC。

贡献社区赞助