Astro 5.2

作者
Matt Kane
Emanuele Stoppa
Florian Lefebvre

Astro 5.2 现已发布！2025 年的第一个次要版本包括 Tailwind 4 支持、在页面中访问配置值的新方式、更好的尾部斜杠处理以及对外部重定向的支持。

现在还是元月，把尝试这些新功能作为你的新年决心吧！

要升级现有项目，请使用自动化的 @astrojs/upgrade CLI 工具。或者，通过运行包管理器的升级命令来手动升级

# Recommended:
npx @astrojs/upgrade


# Manual:
npm install astro@latest
pnpm upgrade astro --latest
yarn upgrade astro --latest

Tailwind 4 支持

随着 v4 的发布，Tailwind CSS 现在提供了一个 @tailwindcss/vite 插件，可以直接添加到你的 Astro 项目中。这简化了 Astro 中的 Tailwind 使用体验，现在是 Astro 中使用 Tailwind 4 的推荐方式。

Astro 5.2 增加了对该 Vite 插件的原生支持，astro add tailwind 命令现在会将该插件添加到你的 Astro 配置中，并创建一个导入 Tailwind 样式的默认 CSS 文件。

因此，@astrojs/tailwind 集成现已弃用，但仍将支持旧版本的 Tailwind。要升级到 Tailwind 4，请卸载该集成，并使用更新后的 astro add tailwind 命令或遵循 Tailwind 文档进行手动安装。

感谢 Eveeifyeve 在 Tailwind 4 处于 alpha 阶段时率先对其提供支持，尽管最终使用了不同的实现方式。

尾部斜杠重定向

路径是否应带有尾部斜杠是 Web 开发中常见的争议。然而，大家都同意它应该保持一致。重复内容不利于 SEO，也会让用户感到困惑。

Astro 长期以来一直允许你配置路由是否应匹配带或不带尾部斜杠的路径，但以前这意味着对于不正确的路径会返回“未找到”页面，或者由主机来处理冲突。Astro 5.2 将根据 astro.config.mjs 中的 trailingSlash 选项，自动将你的按需渲染路由重定向到正确的路径。

现在，无论你的访问者导航到 /about/、/about 还是 /about/// 都没关系。在生产环境中，他们总是会到达正确的页面。对于 GET 请求，重定向将是 301（永久）重定向；对于所有其他请求方法，它将是 308（永久，并保留请求方法）重定向。

在开发过程中，Astro 将显示一个错误页面而不是重定向，以帮助你捕获任何错误配置和无效链接。

要启用尾部斜杠重定向，请在 astro.config.mjs 中设置 trailingSlash 选项

astro.config.mjs
export default defineConfig({
  adapter: node({ mode: 'standalone' }),
  trailingSlash: 'never', // or 'always'
});

欲了解更多信息，请参阅 trailingSlash 文档。

外部重定向

Astro 现在支持直接从配置中定义到 http 或 https 目的地的外部重定向。

就像 Astro 2.9 以来提供的内部重定向一样，通过适配器，你也可以将一个对象作为值提供。这允许你在新的 destination 之外指定一个 status 代码。

import {defineConfig} from "astro/config"


export default defineConfig({
    redirects: {
        "/about": "https://example.com/about",
        "/news": {
            status: 302,
            destination: "https://example.com/news"
        }
    }
})

有关更多详细信息，请参阅更新的 redirects 配置文档。

Markdown 中的 TOML Frontmatter

Astro 对 Markdown 和 MDX 的出色支持一直包括 YAML frontmatter，无论是在文件导出还是内容集合中。通过本次发布，Astro 现在也支持这两种情况下的 TOML frontmatter。这对于从其他框架（如 Hugo）将带有 TOML frontmatter 的现有内容文件添加到你的项目非常有用，或者你可能只是更喜欢 TOML 而非 YAML！

在你的内容文件中使用 TOML frontmatter 不需要任何配置：只需使用 +++ 来分隔 frontmatter，Astro 就会将其解析为 TOML。

+++
date = 2025-01-30
title = 'Use TOML frontmatter in Astro!'
[params]
  author = 'Houston'
+++


# Support for TOML frontmatter is here!

感谢 Colin Bate 贡献了此功能。

实验性功能：astro:config

Astro 提供了多种方式从项目文件中访问配置设置：环境变量、.astro 文件中的 Astro 全局对象以及中间件和端点中的 context 变量。但是，很难记住信息在哪里可用：是 import.meta.env.BASE 还是 Astro.base？

通过 astro:config，我们希望提供一种*单一*的方式，可以从项目内的任何地方读取最有用的配置选项。而且，由于它是 Astro，我们考虑了类型安全！

这个虚拟模块暴露了两个子模块（/client 和 /server），用于访问不同子集的配置值。通过只向客户端提供部分数据，这保护了你的信息。

要使用这个新的虚拟模块，你需要通过实验性标志启用它

import {defineConfig} from "astro/config"


export default defineConfig({
    trailingSlash: "always",
    experimental: {
        serializeConfig: true
    }
})

然后，从 Astro 项目内的任何文件，你都可以使用这个虚拟模块

src/utils.js
import {trailingSlash} from "astro:config/client"


export function appendForwardPath(path) {
    if (trailingSlash === "always") {
        return path.endsWith("/") ? path : path + "/"
    }
    return path
}

有关此新实验性功能的更多信息，请参阅序列化配置文档。

我们希望最终弃用其他读取这些属性的方式，并使 astro:config 成为在 Astro 项目中访问配置值的实际标准。请加入活跃讨论，在序列化配置 RFC 中留下你的反馈，并帮助塑造此功能的未来！

实验性功能：禁用 React 流式传输

@astrojs/react 集成现在允许你禁用 React 流式传输。如果你正在使用与流式传输不兼容的库（例如许多 CSS-in-JS 库），这会很有用。要禁用 React 流式传输，请升级 @astrojs/react 集成

# Recommended:
npx @astrojs/upgrade


# Manual:
npm install @astrojs/react@latest
pnpm upgrade @astrojs/react --latest
yarn upgrade @astrojs/react --latest

然后在 astro.config.mjs 中将集成的 experimentalDisableStreaming 选项设置为 true

astro.config.mjs
export default defineConfig({
  integrations: [
    react({
      experimentalDisableStreaming: true,
    }),
  ],
});

有关更多信息，请参阅 @astrojs/react 文档。

感谢来自《华盛顿邮报》的 Arturo Silva 贡献了此功能。

错误修复

自 5.1 版本发布以来，我们进行了大量的错误修复。请查看更新日志了解所有详细信息。

鸣谢

感谢所有为此版本做出贡献的人，包括 Arturo Silva、Colin Bate、Sarah Rainsberger、Matthew Phillips、HiDeoo、Bjorn Lu、Armand Philippot、Yan Thomas 以及更多人。

我们很高兴看到你用 Astro 5.2 构建出什么！