Skip to content
Astro v5 is here! Learn how to upgrade your site

升级 Astro

本指南介绍如何更新 Astro 版本和相关依赖、如何了解从一个版本到下一个版本的变化以及如何理解 Astro 的版本控制系统和相应的文档更新。

¥This guide covers how to update your version of Astro and related dependencies, how to learn what has changed from one version to the next, and how to understand Astro’s versioning system and corresponding documentation updates.

有什么变化？

标题部分 有什么变化？

¥What has changed?

Astro 的最新版本是 v5.1.1。

¥The latest release of Astro is v5.1.1.

你可以在我们的 升级指南 中找到 Astro’s changelog, and important instructions for upgrading to each new major version 中所有更改的详尽列表。

¥You can find an exhaustive list of all changes in Astro’s changelog, and important instructions for upgrading to each new major version in our upgrade guides.

升级升级到最新版本

标题部分 升级升级到最新版本

¥Upgrade to the latest version

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

¥Update your project’s version of Astro and all official integrations to the latest versions with one command using your package manager:

终端窗口
# Upgrade Astro and official integrations together
npx @astrojs/upgrade

手动升级

标题部分 手动升级

¥Manual Upgrading

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

¥To update Astro and integrations to their current versions manually, use the appropriate command for your package manager.

终端窗口
# Example: upgrade Astro with React and Tailwind integrations
npm install astro@latest @astrojs/react@latest @astrojs/tailwind@latest

安装特定版本号

标题部分 安装特定版本号

¥Install a specific version number

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

¥To install a specific version of Astro or integrations, use the appropriate command for your package manager.

终端窗口
npm install astro@4.5.3 @astrojs/react@3.0.10

文档更新

标题部分 文档更新

¥Documentation updates

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

¥This documentation is updated for each minor release and major version release. When new features are added, or existing usage changes, the docs will update to reflect the current behavior of Astro. If your project is not updated, then you may notice some behaviors do not match the up-to-date documentation.

新功能将添加到文档中，并带有添加时的特定版本号。这意味着如果你尚未更新到 Astro 的最新版本，某些记录的功能可能不可用。在尝试使用新功能之前，请务必检查 Added in: 版本号并确保你的项目已更新！

¥New features are added to docs with the specific version number in which they were added. This means that if you have not updated to the latest release of Astro, some documented features may be unavailable. Always check the Added in: version number and make sure your project is updated before attempting to use new features!

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

¥If you have not upgraded to the latest major version of Astro, you may encounter significant differences between the Astro documentation and your project’s behavior. We strongly recommend upgrading to the current major version of Astro as soon as you are able. Both the code and the documentation for earlier versions is unsupported.

升级指南

标题部分 升级指南

¥Upgrade Guides

在每个 主要版本发布 之后，你都会找到一个升级指南，其中包含有关重要更改的信息以及升级项目代码的说明。

¥After every major version release, you will find an upgrade guide with information about important changes and instructions for upgrading your project code.

Astro 主文档页面始终准确适用于最新发布的 Astro 版本。它们不会描述或比较以前版本中的工作方式，也不会高亮更新或更改的行为。

¥The main Astro documentation pages are always accurate for the latest released version of Astro. They do not describe or compare to how things worked in previous versions, nor do they highlight updated or changed behavior.

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

¥See the upgrade guides below for an explanation of changes, comparing the new version to the old. The upgrade guides include everything that could require you to change your own code: breaking changes, deprecations, feature removals and replacements as well as updated usage guidance. Each change to Astro includes a “What should I do?” section to help you successfully update your project code.

旧文档（未维护）

标题部分 旧文档（未维护）

¥Older docs (unmaintained)

Astro 旧版本的文档未维护，但可作为静态快照使用。如果你无法升级项目但仍希望查阅指南和参考，请使用以下版本的文档：

¥Documentation for older versions of Astro is not maintained, but is available as a static snapshot. Use these versions of docs if you are unable to upgrade your project, but still wish to consult guides and reference:

语义版本控制

标题部分 语义版本控制

¥Semantic versioning

Astro 尝试尽可能遵守 语义版本控制，这是一组规则，开发者用来确定如何为发布分配版本号。语义版本遵循可预测的模式，以告知用户他们可以预期从一个版本到下一个版本的变化类型。

¥Astro attempts to adhere as much as possible to semantic versioning, which is a set of rules developers use to determine how to assign a version number to a release. Semantic version follows a predictable pattern to inform users of the kind of changes they can expect from one version to the next.

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

¥Semantic versioning enforces a pattern of X.Y.Z for software version numbers. These values represent major (X), minor (Y), and patch (Z) updates.

补丁更改

标题部分 补丁更改

¥Patch changes

补丁更改是最不具破坏性的更改。它们不会改变你使用 Astro 的方式，更新时也不需要更改你自己的代码。

¥Patch changes are the least disruptive changes. They do not change the way you use Astro, and no change to your own code is required when you update.

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

¥When Astro issues a “patch” version, the last number increases. (e.g. astro@4.3.14 -> astro@4.3.15)

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

¥Patches may be released for reasons such as:

  • 不会改变 Astro 功能的内部更改：

    • refactors

    • 性能改进

    • 增加或更改测试覆盖率

    • 与所述文档和预期行为保持一致

  • 改进了日志记录和错误消息。

  • 发布失败后重新发布。

补丁更改还包括大多数错误修复，即使在用户利用现有的意外或不良行为的情况下也是如此。

¥Patch changes also include most bug fixes, even in cases where users were taking advantage of existing unintended or undesirable behavior.

小改动

标题部分 小改动

¥Minor changes

次要版本主要引入你可能希望尝试的新功能和改进，但不需要更改你的代码。某些现有功能也可能会在小版本中被弃用（标记为在未来版本中删除，但继续运行），让你有机会为最终删除它们做好准备。

¥Minor releases primarily introduce new features and improvements that you may wish to try, but require no changes to your code. Some existing features may also be deprecated (marked for deletion in a future version while continuing to function) in a minor release, giving you the opportunity to prepare for their eventual removal.

次要版本包括以下更改：

¥Minor releases include changes such as:

  • 弃用现有功能/选项，并警告它们将在即将发布的主要版本中删除。

  • 引入新功能。

  • 在集成钩子中引入新选项。

  • 在 astro/app 中引入新功能，特别是用于创建新适配器。

次要版本可能同时包含较小的补丁更改。

¥A minor release may also include smaller, patch changes at the same time.

重大更改

标题部分 重大更改

¥Major changes

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

¥Major releases will include breaking changes to at least some existing code. These breaking changes are always documented in an “Upgrade to vX” guide in Astro.

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

¥Major releases allow Astro to make significant changes not only to internal logic, but also to intended behavior and usage. Documentation will be updated to reflect the latest version only, and static, unmaintained snapshots of older docs are available as a historical record for older projects that are not yet upgraded.

主要版本包括以下更改：

¥Major releases include changes such as:

  • 删除以前弃用的功能。

  • 现有功能的更改。

  • 集成钩子中现有选项的更改。

  • astro/app 中现有选项和功能的更改，特别是用于创建新适配器的选项。

主要版本可能还包含一些非重大更改和改进，这些更改和改进通常会在次要版本或补丁版本中单独发布。

¥A major release may also include some non-breaking changes and improvements that would normally be released separately in a minor or patch release.

异常

标题部分 异常

¥Exceptions

  • 实验性功能。在不遵守语义版本控制的情况下发布 Astro 版本，使 Astro 开发者在开发实验性功能期间具有最大的灵活性，可以进行探索，甚至彻底改变方向。因此，这些功能的行为可能会因小改动和补丁更改而中断。

    这些功能通常伴随着持续的公共 考虑请求 (RFC) 第 3 阶段。预计测试版用户将关注更新，并在讨论中留下早期反馈，以帮助指导这些功能的开发。

    一旦这些功能超出实验期，它们将遵循正常的语义版本控制合同。

  • 改进了文档（例如参考和错误消息）。它们是从 docs 存储库的源代码构建的。这允许 Astro 在文档源内容存储在主 astro 存储库中的情况下快速更新文档修复和改进。

Node.js 支持和升级政策

标题部分 Node.js 支持和升级政策

¥Node.js support and upgrade policies

支持

标题部分 支持

¥Support

升级

标题部分 升级

¥Upgrade

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

¥The following rules define when Astro may deprecate, drop, or add support for versions of Node.js:

  • 当下一个偶数版本的 Node.js 发布时，奇数版本的 Node.js 可能会被弃用和/或删除。此更改可在 Astro 的小版本中发生，在 Astro Core 团队决定的合理延长支持期之后。

  • 在 Astro 的小版本中可以升级 Node.js 的最低维护 LTS（在同一主要范围内，例如从 v18.14.* 到 v18.20.*）版本。

    • 安全异常：如果影响 Astro 的 Node.js 安全漏洞被披露并修复，核心团队可以在补丁版本中提升维护 LTS 的最低版本。

  • 仅在 A​​stro 的主要版本中升级 Node.js 的次要或主要版本（不是维护 LTS）。

    • 安全异常：如果影响 Astro 的 Node.js 安全漏洞被披露并修复，核心团队可以在次要版本中提高最低版本。

扩展维护

标题部分 扩展维护

¥Extended maintenance

Core 团队将仅为一个先前的主要版本提供安全修复的扩展维护。这意味着如果当前主要版本是 v4.*，核心团队将支持端口安全修复并发布新的 v3.* 版本。

¥The Core team will provide extended maintenance for security fixes only for one previous major version. This means that if the current major is v4.*, the Core team will back port security fixes and issue a new v3.* release.

Astro 中文网 - 粤ICP备13048890号