Astro 2.6：中间件

作者
Matthew Phillips
Emanuele Stoppa
Bjorn Lu
Ben Holmes
Erika

Astro 2.6 发布，这是一个重大版本！几个实验性功能已被标记为稳定，现在可以在所有 Astro 项目中使用（无需“实验性”标志）。

Astro 2.6 还引入了新功能和改进，包括用于管理重定向的全新实验性功能。

如果您已经安装了 Astro，您可以通过在项目中运行 `upgrade` 命令（使用您选择的包管理器）将其升级到 2.6。

npm install astro@latest
pnpm upgrade astro@latest
yarn upgrade astro@latest

顺便说一下，也请升级您安装的任何 @astrojs/* 集成和适配器！

中间件

中间件现在是稳定的，并且在所有项目中无需实验性标志即可使用。中间件允许您在页面渲染并返回给用户之前或之后运行代码。这为 Astro 项目带来了新的控制层，并解锁了用于认证、重定向、头部修改等的新钩子。

src/middleware.ts
export async function onRequest(context, next) {
  // Do something before the request is handled.
  const response = await next()
  // Or, do something before the response is returned.
  return response
}

Astro 2.6 还引入了一个新的 `locals` 对象，用于从中间件向下传递数据。附加到 `locals` 对象的任何数据都会被持久化，并可在任何 Astro 页面组件或 API 路由函数中的 `Astro.locals` 全局对象中读取。

这是一个如何在中间件中实现基本认证检查的示例，将加载的用户上下文向下传递到页面路由：

src/middleware.ts
// Example: A simple authentication check in middleware.
export async function onRequest({ cookies, locals }, next) {
  // Check for the "sid" user session ID cookie.
  // Return a 405 (Not Allowed) if the cookie is missing.
  const sessionId = cookies.get("sid");
  if (!sessionId) {
    return new Response(null, {status: 405});
  }
  // Use your own `getUser()` function to validate the user.
  // Return a 405 (Not Allowed) if the user isn't real.
  const user = await getUser(sessionId);
  if (!user) {
    return new Response(null, {status: 405});
  }
  // Attach the loaded user to the `locals` object.
  // Now, it can be read in the page route!
  locals.user = user;
  // Return `next()` to return the response.
  return next();
}

现在，`locals.user` 对象保证存在于您的项目中，并且可以在任何渲染的页面或 API 路由处理程序中读取。

src/pages/index.astro
---
const { user } = Astro.locals
---


<h1>Hello {user.name}!</h1>

中间件最初在 Astro 2.4 中作为实验性标志引入。该 API 现在是稳定的，并且无需标志即可供所有 Astro 开发者使用。阅读我们的中间件文档指南以了解更多信息。

混合 SSR 输出模式

Astro 的新混合 SSR 输出模式现在是稳定的，并且无需实验性标志即可供所有 Astro 开发者使用。将 `output: "hybrid"` 设置为允许您将交互式 API 路由和页面混合到一个站点中，同时默认保持整个项目是静态和预渲染的。

astro.config.mjs
export default defineConfig({
  output: "hybrid",
  adapter: netlify(),
})

Astro 的新 `“hybrid”` 输出模式有助于弥合静态和动态之间的差距。混合输出模式在您的项目中解锁与原始 `“server”` 输出模式相同的 SSR 功能，但有一个关键区别：每个页面将默认进行静态预渲染。这更接近 `“static”` 构建输出的行为，其中每个页面都预渲染为 HTML，以便服务器或 CDN 即时响应。但与 `“static”` 模式不同，混合输出模式在您的构建输出中包含一个服务器，因此您现在可以向您的站点添加额外的动态页面和 API。

例如，一个机构可以使用 Astro 的新混合输出模式，通过几个步骤为其静态网站添加一个动态的“联系我们”表单处理程序。将 `output` 选项设置为 `“hybrid”`（如果尚未添加部署适配器）。这将保持与以前相同的“默认静态”行为，但您现在可以使用 `export const prerender = false` 将该表单的 API 路由标记为动态，以便它在每次表单提交时运行。

src/pages/api/form-handler.ts
// Mark the page as `prerender = false` to skip pre-rendering
// and run the API endpoint in the server on every submission.
export const prerender = false


export function post({ request }) {
  // ...
}

此功能由 Astro 社区成员 @MoustaphaDev 贡献，并源自我们的公共路线图和 RFC 流程。谢谢！

自定义客户端指令

自定义客户端指令现在是稳定的，并且无需实验性标志即可供所有 Astro 开发者和集成作者使用。

客户端指令是 Astro 岛屿架构的基石。它们控制交互式 UI 如何在您的页面上加载，以组件为单位。Astro 有许多内置指令，例如 `client:idle`（“嘿 Astro，当页面空闲时加载此按钮”）和 `client:visible`（“嘿 Astro，仅当此图片轮播在页面上可见时才加载它”）。以前无法定义您自己的自定义客户端指令，直到现在。

例如，您现在可以定义自己的 `client:hover` 指令，它只会在用户悬停时加载并激活交互式组件。

astro.config.mjs
import { defineConfig } from "astro/config"
import onHoverDirective from "./directives/client-hover.js"


export default defineConfig({
  integrations: [onHoverDirective()],
})

添加后，该集成将定义 `client:hover` 行为，以便您可以在自己的项目中使用它。

<Counter client:hover />

创建您自己的客户端指令，或将其发布到 npm 以与他人共享！

自定义客户端指令最初在 Astro 2.5 中作为实验性标志引入。该 API 现在是稳定的，并且无需标志即可供所有 Astro 开发者使用。阅读我们的自定义客户端指令指南以了解更多信息。

CSS 内联

Astro 2.6 引入了一个新的配置选项，用于自动将小段 CSS 内联到您的 HTML 中。通过减少加载页面所需的请求数量和外部样式表，此优化可以加快大多数页面（尤其是在首次加载时）的速度。您今天就可以通过在配置文件中设置 `inlineStylesheets: "auto"` 来尝试此功能。

astro.config.mjs
import { defineConfig } from "astro/config"


export default defineConfig({
  build: {
    inlineStylesheets: "auto",
  },
})

自动 CSS 内联很可能成为 Astro 3.0 中的默认行为。阅读我们的配置参考，了解有关此选项以及如何为您的项目配置它的更多信息。

此功能由 Astro 社区成员 @lilnasy 贡献，并源自我们的公共路线图和 RFC 流程。谢谢！

重定向（实验性）

Astro 2.6 引入了一项实验性新功能，以便更轻松地在您的项目中添加重定向。要使用它，您需要在项目配置文件中启用实验性标志 `experimental.redirects`。

astro.config.mjs
import { defineConfig } from "astro/config"


export default defineConfig({
  redirects: {
    "/old": "/new",
  },
  experimental: {
    redirects: true,
  },
})

传统上，重定向一直由开发者自行解决。这增加了开发者的工作量，并且在不同主机上以及以在开发和生产环境中一致运行的方式解决起来尤其困难。

Astro 的新 `redirects` 功能通过一个 API 解决了这个问题，该 API 允许您直接在 Astro 配置中管理重定向。这适用于开发和生产环境，并且可以使用我们现有的 `adapter` API 进一步优化以适应特定主机。例如，Netlify 适配器会自动将您的重定向转换为 Netlify 特定的 `_redirects` 文件，以通过其 CDN 实现最快的性能。

我们的目标是拥有一种可靠的方式来配置重定向，使其适用于所有受支持的主机和适配器。我们正在此实验期间征求反馈，因此请尝试并与我们分享您在 Discord 上的经验。

Markdoc 改进

Astro 对Markdoc 的支持随着 `@@astrojs/markdoc` 的最新版本而持续改进。这个新版本带来了与 Astro 中的 Markdown 和 MDX 完全对等的功能，包括标题中自动生成 `id`、更好的语法高亮支持以及通过 `extends` 支持配置扩展。

我们与 Stripe 的 Markdoc 团队紧密合作，不断改进 Astro 中的内容创作体验。看到 Markdoc 生态系统不断发展令人兴奋，我们很自豪能成为其中的一部分！

语言工具改进

Astro 的语言工具在 `@@astrojs/language-server` 2.0 版本和Astro 的 2.0 VSCode 扩展发布后获得了重大升级。此版本完成了对 Volar 的重大重写和内部迁移，以提高性能、功能和稳定性。

Volar 是 Vue 团队开发的通用语言工具框架。使用像 Volar 这样的框架为我们的语言服务器带来了许多好处，类似于 Astro 内部使用 Vite 的方式。Volar 让我们减少了在工具方面重复造轮子的时间，而将更多时间投入到为用户构建功能上。VSCode、`astro check` 和所有其他 Astro 语言服务器的消费者都将从这一变化中受益。

Volar 正在迅速成为所有语言都可以构建在其上的标准框架，我们很高兴能支持这个项目。我们期待继续为包括 Astro 开发者在内的所有人改进 Volar。

特别感谢 Johnson Chu（Volar 维护者）在此项目上给予我们的帮助！