Upgrade 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?
Section titled What has changed?The latest release of Astro is v4.16.14.
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
Section titled Upgrade to the latest versionUpdate 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 togethernpx @astrojs/upgrade# Upgrade Astro and official integrations togetherpnpm dlx @astrojs/upgrade# Upgrade Astro and official integrations togetheryarn dlx @astrojs/upgradeManual Upgrading
Section titled Manual UpgradingTo update Astro and integrations to their current versions manually, use the appropriate command for your package manager.
# Example: upgrade Astro with React and Tailwind integrationsnpm install astro@latest @astrojs/react@latest @astrojs/tailwind@latest# Example: upgrade Astro with React and Tailwind integrationspnpm add astro@latest @astrojs/react@latest @astrojs/tailwind@latest# Example: upgrade Astro with React and Tailwind integrationsyarn add astro@latest @astrojs/react@latest @astrojs/tailwind@latestInstall a specific version number
Section titled Install a specific version numberTo 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.10pnpm add astro@4.5.3 @astrojs/react@3.0.10yarn add astro@4.5.3 @astrojs/react@3.0.10Documentation updates
Section titled Documentation updatesThis 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.
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!
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
Section titled Upgrade GuidesAfter every major version release, you will find an upgrade guide with information about important changes and instructions for upgrading your project code.
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.
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)
Section titled Older docs (unmaintained)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
Section titled Semantic versioningAstro 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.
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
Section titled Patch changesPatch 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.
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:
- Internal changes that do not change Astro’s functionality:
- refactors
- performance improvements
- increase or change in test coverage
- aligning with stated documentation and expected behavior
- Improvements to logging and error messages.
- Re-releases after a failed release.
Patch changes also include most bug fixes, even in cases where users were taking advantage of existing unintended or undesirable behavior.
Minor changes
Section titled Minor changesMinor 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:
- Deprecations of existing features/options with a warning that they will be removed in an upcoming major release.
- Introduction of new functionalities.
- Introduction of new options in the integration hooks.
- Introduction of new functionalities in
astro/app, notably used for creating new adapters.
A minor release may also include smaller, patch changes at the same time.
Major changes
Section titled Major changesMajor 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.
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:
- Removal of previously deprecated functionalities.
- Changes of existing functionalities.
- Changes of existing options in the integration hooks.
- Changes of existing options and functionalities in
astro/app, notably used for creating new adapters.
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
Section titled Exceptions-
Experimental features. Releasing versions of Astro without adhering to semantic versioning allows Astro developers the greatest flexibility to explore, and even radically change course, during the development of experimental features. Therefore, the behavior of these features can break in minor and patch changes.
These features are usually accompanied by an ongoing, public Request for Consideration (RFC) stage 3. It is expected that beta users will follow for updates, and leave early feedback on the discussion to help guide development of these features.
Once these features are out of their experimental period, they will follow the normal semantic versioning contract.
-
Improvements to the documentation (e.g. reference and error messages). They are built from source for the
docsrepository. This allows Astro to quickly update docs fixes and improvements in the cases where documentation source content is stored in the mainastrorepository.
Node.js support and upgrade policies
Section titled Node.js support and upgrade policiesSupport
Section titled Support- Astro supports the latest Maintenance LTS version of Node.js.
- Astro supports the current Active LTS version of Node.js
- Astro can support odd versions of Node.js.
Upgrade
Section titled UpgradeThe following rules define when Astro may deprecate, drop, or add support for versions of Node.js:
- Odd versions of Node.js can be deprecated and/or dropped when the next even version of Node.js published. This change can occur in a minor release of Astro, after a reasonable period of extended support as decided by the Astro Core team.
- Upgrading the minimum Maintenance LTS (within the same major range, e.g. from
v18.14.*tov18.20.*) version of Node.js can occur in a minor release of Astro.- Security exception: If a security flaw in Node.js that affects Astro is disclosed and fixed, the Core team can bump the minimum version of the Maintenance LTS in a patch release.
- Upgrading minor or major versions of Node.js (not Maintenance LTS) occurs only in major versions of Astro.
- Security exception: If a security flaw in Node.js that affects Astro is disclosed and fixed, the Core team can bump the minimum version in a minor release.
Extended maintenance
Section titled Extended maintenanceThe 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.