Astro 5.5

作者
Matt Kane

Astro 5.5 深入探索,为图表工具提供了更好的支持,改进了 Markdown 兼容性,并提供了类型安全的会话!

🧜‍♀️ 潜入 Astro 的新功能之海,体验这些改进

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

# Recommended:
npx @astrojs/upgrade
# Manual:
npm install astro@latest
pnpm upgrade astro --latest
yarn upgrade astro --latest

更好地支持 Markdown 中的绘图工具

Mermaid 和 D2 等工具允许您在 Markdown 代码块中定义图表,然后将其呈现在内容中。到目前为止,在 Astro 中使用这些工具可能会很麻烦,因为 Astro 的默认语法高亮会干扰代码块的渲染方式。

Astro 5.5 在 Markdown 配置中引入了一个新的 excludeLangs 选项,可以跳过对特定语言代码块的语法高亮。这使得您无需禁用其他代码块的语法高亮即可使用此类工具。

以下是如何配置 Astro 以在安装 rehype-mermaid 插件后禁用 mermaid 语言高亮的示例:

astro.config.mjs
import { defineConfig } from 'astro/config';
import rehypeMermaid from 'rehype-mermaid';
export default defineConfig({
markdown: {
syntaxHighlight: {
type: 'shiki',
excludeLangs: ['mermaid', 'math'],
},
rehypePlugins: [rehypeMermaid],
},
});

然后,您可以直接在 Markdown 内容中创建图表

```mermaid
graph TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug]
D --> B
```

这将作为图表呈现在您的页面中。

非常感谢 Chris Chua 的贡献。

类型安全的实验性会话

Astro 5.5 增加了对会话数据进行适当 TypeScript 类型支持,让您告别 any 类型错误。会话存储的实验性支持已在 Astro 5.1 中添加,但以前所有会话数据都是无类型的。现在,您可以通过在项目的 src/env.d.ts 文件中扩展全局 App.SessionData 接口来定义会话数据的类型:

src/env.d.ts
declare namespace App {
interface SessionData {
user: {
id: string;
email: string;
};
lastLogin: Date;
}
}

这是可选的,任何未在此接口中定义的键都将被视为 any 类型。但是,定义类型将为您的网站中的会话数据提供准确的类型检查和自动补全功能。

---
const user = await Astro.session.get('user');
// `user` is properly typed as `{ id: string; email: string; } | undefined`
const something = await Astro.session.get('something');
// `something` is typed as `any` since it's not defined in the interface
// TypeScript will catch this error:
Astro.session.set('user', 1); // Error: Type 'number' is not assignable to type '{ id: string; email: string; }'
---

这一改进使在 Astro 中使用会话更加可靠,并有助于在开发时而不是运行时捕获潜在错误。

有关更多信息,请参阅实验性会话文档

改进的标题 ID 兼容性

Astro 5.5 引入了一个新的experimental.headingIdCompat 标志,该标志生成的标题 ID 与其他常见的 Markdown 处理器(例如 GitHub 和 npm 使用的处理器)保持一致。

默认情况下,Astro 会移除为其包含特殊字符的标题生成的 ID 末尾的连字符。此行为与其他常见的 Markdown 处理器不同,这可能会导致在不同平台之间链接到标题时出现不一致。

通过新的配置标志,您现在可以确保您的标题 ID 遵循与其他平台相同的约定。

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
headingIdCompat: true,
},
});

这对于那些在 GitHub、npm 文档和您的 Astro 网站之间共享锚点链接的站点特别有用。

实验性功能:保留样式和脚本标签的顺序

实验性标志不只用于酷炫的新功能。有时,事情就是必须改变。我们还使用实验性标志来谨慎地引入最终将成为新默认行为的破坏性更改。experimental.preserveScriptOrder 就是其中之一!

当在同一页面上渲染多个 <style><script> 标签时,Astro 当前会在生成的 HTML 输出中反转它们的顺序。这可能会导致意想不到的结果,例如在开发模式下应用的 CSS 样式在网站构建后被较早的样式标签覆盖。

您可以在配置中启用它,如下所示:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
preserveScriptOrder: true,
},
});

将新的 preserveScriptOrder 标志设置为 true 后,Astro 将按照定义顺序生成您的样式和脚本。如果您之前为了弥补 Astro 的行为而故意以乱序编写这些内容,则需要更新您的代码。

我们认为这项更改从长远来看对每个人都有意义,因此我们鼓励您现在就进行测试,以确保在它成为默认行为之前能够正常工作。

感谢JaneSmith 首先发现此问题,以及Reuben Tier 贡献了编译器修复!

错误修复

一如既往,自 5.4 版本发布以来,我们一直在努力修复问题。有关所有详细信息,请参阅更新日志

鸣谢

感谢所有为此版本做出贡献的人,包括 Chris SwithinbankEmanuele StoppaReuben TierLuiz FerrazSarah RainsbergerHiDeooHappyDevYan ThomasBjorn LuChris Chua 等等。

我们期待看到您使用 Astro 5.5 构建的作品!如果您有问题、意见,或者只是想打个招呼,请访问 Astro Discord