版本政策

如需先前版本的列表，請參閱版本頁面。

穩定版本

穩定的 React 版本（也稱為「最新」版本通道）遵循語義化版本控制（semver）原則。

這表示版本號碼 x.y.z

• 在發布重大錯誤修復時，我們會透過更改z 號碼來進行修補版本發布（例如：從 15.6.2 到 15.6.3）。
• 在發布新功能或非重大修復時，我們會透過更改y 號碼來進行次要版本發布（例如：從 15.6.2 到 15.7.0）。
• 在發布重大變更時，我們會透過更改x 號碼來進行主要版本發布（例如：從 15.6.2 到 16.0.0）。

主要版本也可能包含新功能，任何版本都可能包含錯誤修復。

次要版本是最常見的版本類型。

重大變更

重大變更對每個人來說都不方便，因此我們盡量減少主要版本的數量——例如，React 15 於 2016 年 4 月發布，React 16 於 2017 年 9 月發布，React 17 於 2020 年 10 月發布。

相對地，我們在次要版本中發布新功能。這表示儘管名稱不起眼，但次要版本通常比主要版本更有趣且更引人注目。

穩定性承諾

隨著我們隨著時間推移更改 React，我們會盡量減少利用新功能所需的工作量。如果可能，我們會讓舊的 API 保持運作，即使這表示將其放在單獨的套件中。例如，多年來一直不建議使用 mixins，但它們至今仍透過 create-react-class 支援，許多程式碼庫繼續在穩定、舊有的程式碼中使用它們。

超過一百萬名開發人員使用 React，共同維護數百萬個組件。僅 Facebook 程式碼庫就擁有超過 50,000 個 React 組件。這表示我們需要盡可能簡化升級到新版 React 的過程；如果我們在沒有遷移路徑的情況下進行重大變更，人們將會卡在舊版本上。我們在 Facebook 本身測試這些升級路徑——如果我們不到 10 人的團隊可以獨自更新 50,000 多個組件，我們希望升級對任何使用 React 的人來說都是可管理的。在許多情況下，我們會撰寫自動化腳本來升級組件語法，然後將其包含在開源版本中供所有人使用。

透過警告逐步升級

React 的開發版本包含許多有用的警告。我們會盡可能新增警告，為未來的重大變更做好準備。如此一來，如果您的應用程式在最新版本中沒有警告，它將與下一個主要版本相容。這讓您可以一次升級一個應用程式組件。

開發警告不會影響您應用程式的執行階段行為。如此一來，您可以確信您的應用程式在開發和生產版本之間的行為方式相同——唯一的區別是生產版本不會記錄警告，而且效率更高。（如果您發現有任何不同，請提交問題。）

什麼算是重大變更？

一般來說，我們*不會*針對以下變更提升主要版本號碼

• 開發警告。由於這些不會影響生產行為，我們可能會在主要版本之間新增警告或修改現有警告。事實上，這就是我們能夠可靠地警告即將發生的重大變更的原因。
• 以 unstable_ 開頭的 API。這些是作為實驗性功能提供的，我們對其 API 尚無信心。透過使用 unstable_ 前綴發布這些功能，我們可以更快地迭代並更快地獲得穩定的 API。
• React 的 Alpha 和 Canary 版本。我們提供 React 的 alpha 版本作為及早測試新功能的方法，但我們需要根據在 alpha 期間學到的知識靈活地進行變更。如果您使用這些版本，請注意 API 在穩定版本發布之前可能會發生變化。
• 未記錄的 API 和內部資料結構。如果您存取內部屬性名稱，例如 __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED 或 __reactInternalInstance$uk43rzhitjg，則不提供任何保證。您必須自行負責。

這項政策的設計旨在務實：當然，我們不想造成您的困擾。如果我們針對所有這些變更都提升主要版本，我們最終將會發布更多主要版本，並最終為社群造成更多版本控制的痛苦。這也表示我們無法按照我們想要的速度改進 React。

話雖如此，如果我們預期此清單上的變更會在社群中造成廣泛的問題，我們仍然會盡最大努力提供逐步遷移的路徑。

如果一個次要版本沒有包含任何新功能，為什麼它不是一個修補程式？

次要版本可能不會包含新功能。 語意化版本允許這種情況，它指出 「[次要版本]如果在私有程式碼中引入了大量新功能或改進，則可以遞增。它可能包含修補程式級別的變更。」

然而，這確實引出了一個問題：為什麼這些版本不以修補程式的方式進行版本控制？

答案是，React（或其他軟體）的任何變更都帶有一定風險，可能會以意想不到的方式造成損壞。想像一下，一個修補程式版本修復了一個錯誤，卻意外引入了另一個錯誤。這不僅會干擾開發人員，還會損害他們對未來修補程式版本的信心。如果原始修復程式是針對實際上很少遇到的錯誤，那就更令人遺憾了。

我們在保持 React 版本沒有錯誤方面有著相當良好的記錄，但修補程式版本對可靠性的要求更高，因為大多數開發人員認為它們可以在沒有不良後果的情況下被採用。

基於這些原因，我們僅將修補程式版本保留用於最關鍵的錯誤和安全漏洞。

如果一個版本包含非必要的變更，例如內部重構、實作細節的變更、效能改進或次要錯誤修復，即使沒有新功能，我們也會提升次要版本。

所有發布管道

React 依靠蓬勃發展的開源社群來提交錯誤報告、發起拉取請求和 提交 RFC。為了鼓勵回饋，我們有時會分享包含未發布功能的 React 特殊版本。

React 的每個發布管道都設計用於不同的使用案例

• 最新版 適用於穩定、語意化版本的 React 版本。這是您從 npm 安裝 React 時所獲得的版本。這是您今天已經在使用的管道。直接使用 React 的面向用戶應用程式使用此管道。
• Canary 版 追蹤 React 原始碼儲存庫的主分支。將這些視為下一個語意化版本的候選版本。 框架或其他策劃的設定可以選擇使用此管道，並使用固定版本的 React。 您也可以使用 Canary 版進行 React 與第三方專案之間的整合測試。
• 實驗版 包含穩定版本中沒有的實驗性 API 和功能。這些也追蹤主分支，但啟用了額外的功能標誌。使用此版本可以在新功能發布之前試用它們。

所有版本都會發布到 npm，但只有最新版使用語意化版本控制。預發布版本（Canary 版和實驗版）的版本是根據其內容的雜湊值和提交日期生成的，例如 Canary 版的 18.3.0-canary-388686f29-20230503 和實驗版的 0.0.0-experimental-388686f29-20230503。

最新版和 Canary 版管道都正式支援面向用戶的應用程式，但期望不同:

• 最新版本遵循傳統的語意化版本模型。
• Canary 版 必須固定版本，並且可能包含重大變更。它們適用於想要根據自己的發布時間表逐步發布新的 React 功能和錯誤修復的策劃設定（如框架）。

實驗版僅供測試使用，我們不保證版本之間的行為不會改變。它們不遵循我們用於最新版本發布的語意化版本協定。

藉由將預發布版本發布到與我們用於穩定版本相同的儲存庫，我們能夠利用許多支援 npm 工作流程的工具，例如 unpkg 和 CodeSandbox。

最新版管道

最新版是用於穩定 React 版本的管道。它對應於 npm 上的 latest 標籤。建議所有發布給實際用戶的 React 應用程式都使用此管道。

如果您不確定應該使用哪個管道，請選擇最新版。如果您直接使用 React，這就是您已經在使用的管道。您可以預期最新版的更新將非常穩定。版本遵循語意化版本方案，如 先前所述。

Canary 版管道

Canary 版是一個預發布管道，追蹤 React 儲存庫的主分支。我們使用 Canary 版中的預發布版本作為最新版管道的候選版本。您可以將 Canary 版視為最新版的超集，更新頻率更高。

最新 Canary 版與最新版之間的變更程度與您在兩個次要語意化版本之間看到的變更程度大致相同。但是，Canary 版管道不符合語意化版本控制。您應該預期 Canary 版管道中連續版本之間偶爾會出現重大變更。

除非您遵循 Canary 版工作流程，否則不要直接在面向用戶的應用程式中使用預發布版本。

Canary 版中的版本使用 npm 上的 canary 標籤發布。版本是根據版本的內容雜湊值和提交日期生成的，例如 18.3.0-canary-388686f29-20230503。

使用 Canary 版管道進行整合測試

Canary 版管道也支援 React 與其他專案之間的整合測試。

React 的所有變更在發布給大眾之前，都會經過廣泛的內部測試。然而，在整個 React 生態系統中使用了無數的環境和配置，我們不可能針對每一個環境和配置進行測試。

如果您是第三方 React 框架、函式庫、開發工具或類似基礎架構類型項目的作者，您可以通過定期針對最新變更運行您的測試套件，來幫助我們為您的用戶和整個 React 社群保持 React 的穩定性。如果您有興趣，請按照以下步驟操作

• 使用您偏好的持續整合平台設定 cron 作業。Cron 作業同時受到 CircleCI 和 Travis CI 的支援。

• 在 cron 作業中，使用 npm 上的 canary 標籤，將您的 React 套件更新到 Canary 頻道中的最新 React 版本。使用 npm 命令列工具：

  npm update react@canary react-dom@canary

  或者使用 yarn：

  yarn upgrade react@canary react-dom@canary

• 針對更新後的套件運行您的測試套件。

• 如果一切順利通過，那就太好了！您可以預期您的項目將與下一個 React 次要版本一起正常運作。

• 如果發生意外錯誤，請通過 提交 issue 告知我們。

使用此工作流程的項目是 Next.js。您可以參考他們的 CircleCI 設定 作為範例。

實驗性頻道

與 Canary 類似，實驗性頻道是一個預發布頻道，它追蹤 React 儲存庫的主分支。與 Canary 不同的是，實驗性版本包含尚未準備好廣泛發布的額外功能和 API。

通常，Canary 的更新會伴隨著實驗性頻道的相應更新。它們基於相同的程式碼版本，但使用不同的功能標誌集構建。

實驗性版本可能與 Canary 和 Latest 版本有顯著不同。請勿在面向用戶的應用程式中使用實驗性版本。您應該預期實驗性頻道中的版本之間會頻繁出現重大變更。

實驗性版本在 npm 上使用 experimental 標籤發布。版本號碼由建置內容的雜湊值和提交日期生成，例如 0.0.0-experimental-68053d940-20210623。

實驗性版本中包含哪些內容？

實驗性功能是指尚未準備好向廣大公眾發布的功能，在最終確定之前可能會發生巨大變化。有些實驗可能永遠不會最終確定——我們進行實驗的原因是為了測試提議變更的可行性。

例如，如果在我們宣布 Hooks 時就存在實驗性頻道，我們會在 Hooks 在 Latest 頻道中可用之前幾週將其發布到實驗性頻道。

您可能會發現針對實驗性版本運行整合測試很有價值。這取決於您。但是，請注意，實驗性版本比 Canary 版本更不穩定。我們不保證實驗性版本之間的任何穩定性。

如何瞭解更多關於實驗性功能的資訊？

實驗性功能可能會也可能不會被記錄。通常，在實驗性功能接近在 Canary 或 Latest 頻道中發布之前，它們不會被記錄。

如果某個功能沒有被記錄，它可能會伴隨著一個 RFC。

當我們準備好宣布新的實驗時，我們會在 React 部落格 上發布文章，但这並不意味著我們會公開宣傳每個實驗。

您可以隨時參考我們公開的 GitHub 儲存庫的 歷史記錄，以獲得完整的變更列表。