ESP-IDF 版本簡介
ESP-IDF 的 GitHub 倉庫時常更新，特別是用於開發新特性的 master 分支。
如有量產需求，請使用穩定版本。
發佈版本
您可以通過以下鏈接訪問各個版本的配套文檔：
- 最新穩定版 ESP-IDF：https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
- 最新版 ESP-IDF（即 master 分支）：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/
ESP-IDF 在 GitHub 平臺上的完整發布歷史請見 發佈說明頁面。您可以在該頁面查看各個版本的發佈說明、配套文檔及相應獲取方式。
此外，您還可以直接前往文檔頁面，查看部分 ESP-IDF 版本的配套文檔，具體可通過點擊頁面左下角的小三角標誌，在不同版本間切換。
我該選擇哪個版本？
- 如有量產需求，請使用 最新穩定版本。穩定版本已通過人工測試，後續更新僅修復 bug，主要特性不受影響（更多詳情，請見 版本管理）。
- 如需嘗試/測試 ESP-IDF 的最新特性，請使用 最新版本（在 master 分支上）。最新版本包含 ESP-IDF 的所有最新特性，已通過自動化測試，但尚未全部完成人工測試（因此存在一定風險）。
- 如需使用穩定版本中沒有的新特性，但同時又不希望受到 master 分支更新的影響，您可以將一個最適合您的穩定版本 更新至一個預發佈版本 或 更新至一個發佈分支。
有關如何更新 ESP-IDF 本地副本的內容，請參考 更新 ESP-IDF 章節。
版本管理
ESP-IDF 採用了 語義版本管理方法，即您可以從字面含義理解每個版本的差異。其中
主要版本（例
v3.0）代表有重大更新，包括增加新特性、改變現有特性及移除已棄用的特性。升級至一個新的主要版本（例
v2.1升級至v3.0）意味着您可能需要更新您的工程代碼，並重新測試您的工程，具體可參考 發佈說明頁面 的重大變更 (Breaking Change) 部分。次要版本（例
v3.1）代表有新增特性和 bug 修復，但現有特性不受影響，公開 API 的使用也不受影響。升級至一個新的次要版本（例
v3.0升級至v3.1）意味着您可能不需要更新您的工程代碼，但需重新測試您的工程，特別是 發佈說明頁面 中專門提到的部分。Bugfix 版本（例
v3.0.1）僅修復 bug，並不增加任何新特性。升級至一個新的 Bugfix 版本（例
v3.0升級至v3.0.1）意味着您不需要更新您的工程代碼，僅需測試與本次發佈修復 bug（列表見 發佈說明頁面）直接相關的特性。
查看當前版本
查看 ESP-IDF 本地副本的版本，請使用 git 命令:
cd $IDF_PATH
git describe --tags --dirty
此外，由於 ESP-IDF 的版本也已編譯至固件中，因此您也可以使用宏 IDF_VER 查看 ESP-IDF 的版本（以字符串的格式）。ESP-IDF 默認引導程序可以在設備啓動時打印 ESP-IDF 的版本，但注意代碼中的版本信息僅會在源代碼重新編譯時纔會更新，因此打印出來的版本可能並不是最新的。
幾個 ESP-IDF 版本的例子：
| 版本字符串 | 含義 |
|---|---|
v3.2-dev-306-gbeb3611ca |
master 分支上的預發佈版本。
-
v3.2-dev：爲 v3.2 進行的開發。-
306：v3.2 開發啓動後的 commit 數量。-
beb3611ca：commit 標識符。 |
v3.0.2 |
穩定版本，標籤爲 v3.0.2。 |
v3.1-beta1-75-g346d6b0ea |
v3.1 的 beta 測試版本（可參考 更新至一個發佈分支）。
-
v3.1-beta1 - 預發佈標籤。-
75：添加預發佈 beta 標籤後的 commit 數量。-
346d6b0ea：commit 標識符。 |
v3.0.1-dirty |
穩定版本，標籤爲
v3.0.1。-
dirty 代表 ESP-IDF 的本地副本有修改。 |
Git 工作流
樂鑫 ESP-IDF 團隊的 (Git) 開發工作流程如下：
- 新的改動總是在 master 分支（最新版本）上進行。master 分支上的 ESP-IDF 版本總帶有
-dev標籤，表示“正在開發中”，例v3.1-dev。 - 這些改動將首先在樂鑫的內部 Git 倉庫進行代碼審閱與測試，而後在自動化測試完成後推至 GitHub。
- 新版本一旦完成特性開發（在
master分支上進行）並達到進入 beta 測試的標準，則將該版本簽出至一個新分支（例release/v3.1）。此外，該分支還打上預發佈標籤（例v3.1-beta1）。您可以在 GitHub 平臺上查看 ESP-IDF 的完整 分支列表 和 標籤列表。Beta 預發佈版本可能仍存在大量“已知問題”(Known Issue)。 - 隨着對 beta 版本的不斷測試，bug 修復將同時增加至該發佈分支和
master分支。而且，master分支可能也已經開始爲下個版本開發新特性了。 - 當測試快結束時，該發佈分支上將增加一個 rc 標籤，代表候選發佈 (Release Candidate) ，例
v3.1-rc1。此時，該分支仍屬於預發佈版本。 - 如果一直未發現或報告重大 bug，則該預發佈版本將最終增加“主要版本”（例
v4.0）或“次要版本”標記（例v3.1），成爲正式發佈版本，並體現在 發佈說明頁面 。 - 後續，該版本中發現的 bug 都將在該發佈分支上進行修復。人工測試完成後，該分支將增加一個 bugfix 版本標籤（例
v3.1.1），並體現在 發佈說明頁面 。
更新 ESP-IDF
請根據您的實際情況，對 ESP-IDF 進行更新。
- 如有量產用途，建議參考 更新至一個穩定發佈版本。
- 如需測試/研發/嘗試最新特性，建議參考 更新至 master 分支 。
- 兩者折衷建議參考 更新至一個發佈分支。
註解
在參考本指南時，請首先獲得 ESP-IDF 的本地副本，具體步驟請參考 入門指南 中的介紹。
更新至一個穩定發佈版本
（推薦量產用戶）如需更新至一個新的 ESP-IDF 發佈版本，請參考以下步驟：
- 請定期查看 發佈說明頁面 ，瞭解最新發布情況。
- 如有新發布的 bugfix 版本（例
v3.0.1或v3.0.2）時，請將新的 bugfix 版本更新至您的 ESP-IDF 目錄：
cd $IDF_PATH
git fetch
git checkout vX.Y.Z
git submodule update --init --recursive
- 如有主要版本或次要版本新發布時，請查看發佈說明中的具體描述，並決定是否升級您的版本。具體命令與上方描述一致。
註解
如果您之前在安裝 ESP-IDF 時使用了 zip 文件包，而非通過 Git 命令，則您將無法使用 Git 命令進行版本升級，此屬正常情況。這種情況下，請重新下載最新 zip 文件包，並替換掉之前 IDF_PATH 下的全部內容。
更新至一個預發佈版本
您也可以將您的本地副本簽出（命令 git checkout）至一個預發佈版本或 rc 版本，具體方法請參考 更新至一個穩定發佈版本 中的描述。
預發佈版本通常不體現在 發佈說明頁面。更多詳情，請查看完整 標籤列表。使用預發佈版本的注意事項，請參考 更新至一個發佈分支 中的描述。
更新至 master 分支
註解
ESP-IDF 中 master 分支上的代碼會時時更新，因此使用 master 分支相當在“流血的邊緣試探”，存在一定風險。
如需使用 ESP-IDF 的 master 分支，請參考以下步驟：
本地簽出至 master 分支:
cd $IDF_PATH git checkout master git pull git submodule update --init --recursive
此外，您還應在後續工作中不時使用
git pull命令，將遠端 master 上的更新同步到本地。注意，在更新 master 分支後，您可能需要更改項代碼，也可能遇到新的 bug。如需從 master 分支切換至一個發佈分支或穩定版本，請使用
git checkout命令。
重要
強烈建議您定期使用 git pull 和 git submodule update --init --recursive 命令，確保本地副本的及時更新。舊的 master 分支相當於一個“快照”，可能存在未記錄的問題，且無法獲得支持。對於半穩定版本，請參考 更新至一個發佈分支。
更新至一個發佈分支>
從穩定性來說，使用“發佈分支”相當於在使用 master 分支和穩定版本之間進行折衷，包含一些 master 分支上的新特性，但也同時保證可通過 beta 測試且基本完成了 bug 修復。
更多詳情，請前往 GitHub 查看完整 標籤列表。
舉例，您可以關注 ESP-IDF v3.1 分支，隨時關注該分支上的 bugfix 版本發佈（ 例 v3.1.1 等）:
cd $IDF_PATH
git fetch
git checkout release/v3.1
git pull
git submodule update --init --recursive
您每次在該分支上使用 git pull 時都相當於把最新的 bugfix 版本發佈更新至您的本地副本中。
註解
發佈分支並不會有專門的配套文檔，建議您使用與本分支最接近的版本。