跳到內容

升級 Astro

本指南涵蓋如何更新你的 Astro 版本及相關相依套件、如何了解各版本之間的變更，以及如何理解 Astro 的版本編號系統和對應的文件更新。

有什麼變更？

Section titled “有什麼變更？”

Astro 的最新版本是 v6.1.5。

你可以在 Astro 的變更日誌中找到所有變更的完整清單，以及在我們的升級指南中找到每個新主要版本的重要升級說明。

升級至最新版本

Section titled “升級至最新版本”

使用你的套件管理工具，透過一個指令將專案中的 Astro 和所有官方整合更新到最新版本：

終端機視窗
# 一起升級 Astro 和官方整合
npx @astrojs/upgrade

手動升級

Section titled “手動升級”

若要手動將 Astro 和整合更新至最新版本，請使用你的套件管理工具對應的指令。

終端機視窗
# 範例：升級 Astro 以及 React 和 Partytown 整合
npm install astro@latest @astrojs/react@latest @astrojs/partytown@latest

安裝特定版本號

Section titled “安裝特定版本號”

若要安裝特定版本的 Astro 或整合，請使用你的套件管理工具對應的指令。

終端機視窗
npm install astro@4.5.3 @astrojs/react@3.0.10

文件更新

Section titled “文件更新”

本文件會在每次次要版本和主要版本發布時更新。當新增功能或現有用法有變更時，文件會更新以反映 Astro 的當前行為。如果你的專案尚未更新，你可能會注意到某些行為與最新文件不一致。

新功能會在文件中標註其加入的特定版本號。這表示如果你尚未更新至 Astro 的最新版本，部分已記載的功能可能無法使用。請務必確認 Added in: 的版本號，並在嘗試使用新功能前確保你的專案已更新！

如果你尚未升級至 Astro 的最新主要版本，你可能會遇到 Astro 文件與專案行為之間的顯著差異。我們強烈建議你盡快升級至當前的主要版本。舊版的程式碼和文件均不再受到支援。

升級指南

Section titled “升級指南”

在每次主要版本發布後，你會找到一份升級指南，其中包含重要變更的資訊和升級專案程式碼的說明。

Astro 的主要文件頁面始終精確對應最新發布的 Astro 版本。它們不會描述或比較舊版本的運作方式，也不會特別標註更新或變更的行為。

請參閱以下升級指南，了解新舊版本之間的變更說明。升級指南包含所有可能需要你修改程式碼的內容：重大變更、棄用功能、功能移除和替代方案，以及更新的使用指南。Astro 的每項變更都包含一個「我該怎麼做？」段落，幫助你成功更新專案程式碼。

舊版文件（不再維護）

Section titled “舊版文件（不再維護）”

舊版 Astro 的文件不再維護，但仍以靜態快照的形式提供。如果你無法升級專案但仍希望查閱指南和參考資料，可以使用這些版本的文件：

語意化版本

Section titled “語意化版本”

Astro 盡可能遵循語意化版本，這是一組開發者用來決定如何為版本分配版本號的規則。語意化版本遵循可預測的模式，讓使用者了解從一個版本到下一個版本可以預期的變更類型。

語意化版本規定軟體版本號採用 X.Y.Z 的格式。這些數值分別代表主要版本 (X)、次要版本 (Y) 和修補版本 (Z) 更新。

修補變更

Section titled “修補變更”

修補變更是影響最小的變更。它們不會改變你使用 Astro 的方式，更新時也不需要修改你的程式碼。

當 Astro 發布「修補」版本時，最後一個數字會增加。（例如 astro@4.3.14 -> astro@4.3.15）

修補版本的發布原因包括：

  • 不影響 Astro 功能的內部變更：
    • 重構
    • 效能改善
    • 測試覆蓋率的增加或變更
    • 使行為符合已記載的文件和預期行為
  • 日誌和錯誤訊息的改善。
  • 失敗發布後的重新發布。

修補變更也包含大多數的錯誤修正，即使在使用者利用了現有的非預期或不理想行為的情況下也是如此。

次要變更

Section titled “次要變更”

次要版本主要引入你可能想嘗試的新功能和改善，但不需要修改你的程式碼。某些現有功能也可能在次要版本中被棄用（標記為將在未來版本中刪除，但仍繼續運作），讓你有時間為其最終移除做好準備。

次要版本包含的變更如：

  • 棄用現有功能 / 選項，並警告它們將在即將到來的主要版本中被移除。
  • 引入新功能。
  • 在整合鉤子中引入新選項。
  • 在 astro/app 中引入新功能，主要用於建立新的配接器。

次要版本也可能同時包含較小的修補變更。

主要變更

Section titled “主要變更”

主要版本將包含至少部分現有程式碼的重大變更。這些重大變更總是記錄在 Astro 的「升級至 vX」指南中。

主要版本允許 Astro 對內部邏輯以及預期行為和用法進行重大更改。文件將僅更新以反映最新版本，而靜態的、不再維護的舊版文件快照則作為尚未升級的舊專案的歷史紀錄。

主要版本包含的變更如：

  • 移除先前棄用的功能。
  • 變更現有功能。
  • 變更整合鉤子中的現有選項。
  • 變更 astro/app 中的現有選項和功能，主要用於建立新的配接器。

主要版本也可能包含一些通常會在次要或修補版本中單獨發布的非重大變更和改善。

例外情況

Section titled “例外情況”

  • 實驗性功能。在不遵循語意化版本的情況下發布 Astro 版本，讓 Astro 開發者在開發實驗性功能期間擁有最大的靈活性，甚至可以徹底改變方向。因此，這些功能的行為可能會在次要和修補變更中產生重大改變。

    這些功能通常伴隨著一個進行中的、公開的 Request for Consideration (RFC) 第三階段。預期測試版使用者會持續關注更新，並在討論中提供早期回饋，以協助引導這些功能的開發。

    一旦這些功能結束實驗期，它們將遵循正常的語意化版本契約。

  • 文件改善（例如參考資料和錯誤訊息）。這些是從 docs 儲存庫的原始碼建置的。這讓 Astro 可以在文件來源內容儲存在主要 astro 儲存庫中的情況下，快速更新文件修正和改善。

Node.js 支援和升級政策

Section titled “Node.js 支援和升級政策”

支援

Section titled “支援”

升級

Section titled “升級”

以下規則定義了 Astro 何時可以棄用、停止支援或新增支援 Node.js 版本：

  • 當下一個偶數版本的 Node.js 發布時，奇數版本的 Node.js 可以被棄用和 / 或停止支援。此變更可以在 Astro 的次要版本中進行，但須經過 Astro 核心團隊決定的合理延長支援期。
  • 升級最低 Maintenance LTS 版本（在同一主要版本範圍內，例如從 22.14.* 到 22.20.*）可以在 Astro 的次要版本中進行。
    • 安全性例外：如果披露並修正了一個影響 Astro 的 Node.js 安全漏洞，核心團隊可以在修補版本中提升最低 Maintenance LTS 版本。
  • 升級 Node.js 的次要或主要版本（非 Maintenance LTS）僅在 Astro 的主要版本中進行。
    • 安全性例外：如果披露並修正了一個影響 Astro 的 Node.js 安全漏洞，核心團隊可以在次要版本中提升最低版本。

延長維護

Section titled “延長維護”

核心團隊將僅針對安全修正為前一個主要版本提供延長維護。這表示如果當前主要版本是 v4.*，核心團隊會將安全修正向後移植並發布新的 v3.* 版本。

貢獻 社群 贊助