升级 Astro

本指南涵盖了如何更新你的 Astro 版本及相关依赖、如何了解从一个版本到下一个版本发生了什么变化，以及如何理解 Astro 的版本系统和相应的文档更新。

有什么变化？

Astro 的最新版本是 v4.16.16。

你可以在 Astro 的更新日志中找到所有变化的详尽列表，并且在我们的升级指南中找到升级到每个新的主要版本的重要指导。

升级到最新版本

使用你的包管理器，通过一个命令更新你的项目中的 Astro 及所有官方集成到最新版本：

# 同时升级 Astro 及其官方集成
npx @astrojs/upgrade

# 同时升级 Astro 及其官方集成
pnpm dlx @astrojs/upgrade

# 同时升级 Astro 及其官方集成
yarn dlx @astrojs/upgrade

手动升级

要手动将 Astro 及其集成更新到当前版本，请使用适合你的包管理器的相应命令。

# 示例：将 Astro 及其 React 和 Tailwind 的集成升级
npm install astro@latest @astrojs/react@latest @astrojs/tailwind@latest

# 示例：将 Astro 及其 React 和 Tailwind 的集成升级
pnpm add astro@latest @astrojs/react@latest @astrojs/tailwind@latest

# 示例：将 Astro 及其 React 和 Tailwind 的集成升级
yarn add astro@latest @astrojs/react@latest @astrojs/tailwind@latest

安装特定版本号

要安装特定的 Astro 版本或集成，请使用适合你的包管理器的相应命令。

npm install astro@4.5.3 @astrojs/react@3.0.10

pnpm add astro@4.5.3 @astrojs/react@3.0.10

yarn add astro@4.5.3 @astrojs/react@3.0.10

文档更新

每次次要版本发布和主要版本发布时，本文档都会进行更新。当添加新功能或现有用法发生变化时，文档将更新以反映 Astro 的当前行为。如果你的项目没有更新，那么你可能会注意到一些行为与最新的文档不匹配。

新功能将添加到文档中，并带有添加它们的特定版本号。这意味着，如果你没有更新到 Astro 的最新版本，一些文档中的功能可能无法使用。始终检查 Added in: 版本号，并确保你的项目在尝试使用新功能之前已经更新。

如果你还没有升级到 Astro 的最新主要版本，你可能会遇到 Astro 文档和你的项目行为之间的重大差异。我们强烈建议尽快升级到 Astro 的当前主要版本。早期版本的代码和文档都不再受支持。

升级指南

在每次主要版本发布之后，你会找到一个升级指南，其中包含重要变更的信息和升级项目代码的指示。

Astro 的主要文档页面始终准确反映 Astro 最新发布版本的内容。它们不会描述或比较以前版本的工作方式，也不会突出显示更新或更改的行为。

请参阅下面的升级指南，了解变更的解释，将新版本与旧版本进行比较。升级指南包括所有可能需要你更改自己代码的内容：重大变更、弃用、功能移除和替换以及更新的使用指导。Astro 的每次变更都包括一个“我应该做什么？”部分，以帮助你成功更新项目代码。

旧版本文档（不再维护）

Astro 的旧版本文档不再进行维护，但可以作为静态快照访问。如果你无法升级你的项目，但仍希望查阅指南和参考资料，请使用这些版本的文档：

语义化版本控制

Astro 尽可能地遵循语义化版本控制，这是一套开发者用来决定如何为发布分配版本号的规则。语义化版本遵循一个可预测的模式，以通知用户从一个版本到下一个版本可以期待的变化类型。

语义化版本控制强制执行 X.Y.Z 的模式用于软件版本号。这些值分别代表 主要更新 (X)、次要更新 (Y) 和 补丁更新 (Z)。

补丁更改

补丁更改是最小干扰的更改。它们不会改变你使用 Astro 的方式，当你更新时也不需要对你的代码进行任何更改。

当 Astro 发布一个“补丁”版本时，最后的数字会增加。（例如，astro@4.3.14 -> astro@4.3.15）

可能出于以下原因发布补丁：

不改变 Astro 功能的内部变更：
- 重构
- 性能提升
- 增加或改变测试覆盖率
- 与声明的文档和预期行为保持一致
日志和错误消息的改进。
发布失败后的重新发布。

补丁更改还包括大多数 bug 修复，即使在用户利用现有的非预期或不希望的行为的情况下也是如此。

次要变更

次要版本主要引入了你可能想尝试的新功能和改进，但不需要对你的代码进行任何更改。在次要版本中，一些现有功能可能也会被弃用（在未来的版本中标记为删除，同时继续运行），为你提供了准备最终移除它们的机会。

次要版本包括如下变更：

现有功能/选项的弃用，并警告它们将在即将到来的主要版本中被移除。
引入新的功能。
在集成钩子中引入新的选项。
在 astro/app 中引入新的功能，特别是用于创建新的适配器。

次要版本也可能同时包括较小的，补丁级别的变更。

主要变更

主要版本将包括对至少一些现有代码的重大更改。这些重大更改总是记录在 Astro 的 “升级到 vX 版本” 指南中。

主要版本允许 Astro 不仅对内部逻辑进行重大更改，还对预期的行为和使用进行更改。文档将仅更新以反映最新版本，而静态的、不再维护的旧文档快照可作为尚未升级的旧项目的历史记录。

主要版本包括的更改如下：

移除之前已弃用的功能。
现有功能的更改。
集成钩子中现有选项的更改。
在 astro/app 中现有选项和功能的更改，特别是用于创建新适配器的。

主要版本也可能包括一些非破坏性的更改和改进，这些通常会在次要或补丁版本中单独发布。

异常情况

实验性功能。在不遵守语义版本控制的情况下发布的 Astro 版本，可以让 Astro 开发者在开发实验性功能时拥有最大的灵活性，甚至可以在开发过程中从根本上改变方向。因此，这些功能的行为可能会导致微小的更改和补丁更改。

这些功能通常伴随着一个持续进行的、公开的请求考虑（RFC）第 3 阶段。预期 beta 用户会关注更新，并在讨论中提前反馈，以帮助指导这些功能的开发。

一旦这些功能结束了它们的实验期，它们将遵循正常的语义化版本控制合约。
文档的改进（例如，参考和错误消息）。它们是为 docs 仓库从源代码构建的。这允许 Astro 在文档源内容存储在主 astro 仓库的情况下，快速更新文档修复和改进。

Node.js 支持和升级策略

支持

Astro 支持 最近的 Maintenance LTS 版本的 Node.js。
Astro 支持 当前的 Active LTS 版本的 Node.js。
Astro 也支持 Node.js 的奇数版本。

升级

以下规则定义了 Astro 何时可能弃用、删除或增加对 Node.js 版本的支持：

当 Node.js 发布下一个偶数版本时，可以弃用和/或删除 Node.js 的奇数版本。在 Astro 核心团队决定的合理的延长支持期之后，这种变化可能在 Astro 的次要版本中发生。
升级最低 Maintenance LTS（在相同的主要版本范围内，例如，从 v18.14.* 到 v18.20.*）版本的 Node.js 可以在 Astro 的次要版本中发生。
- 安全例外：如果 Node.js 中的安全漏洞被披露并修复，且影响到 Astro，核心团队可以在补丁版本中提升最低的 Maintenance LTS 版本。
只有在 Astro 的主要版本中，才会升级 Node.js 的次要或主要版本（不是 Maintenance LTS）。
- 安全例外：如果 Node.js 中的安全漏洞被披露并修复，且影响到 Astro，核心团队可以在次要版本中提升最低版本。

延长维护

核心团队将为上一个主要版本仅提供安全修复的延长维护。这意味着如果当前的主要版本是 v4.*，核心团队将回移安全修复并发布一个新的 v3.* 版本。

贡献

社区