Bzlmod 遷移指南

回報問題 查看來源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

由於 WORKSPACE 有所不足，Bzlmod 將取代舊版 WORKSPACE 系統。WORKSPACE 檔案已在 Bazel 8 (2024 年底) 中停用，並將在 Bazel 9 (2025 年底) 中移除。本指南可協助您將專案遷移至 Bzlmod，並捨棄 WORKSPACE 來管理外部依附元件。

為何要遷移至 Bzlmod？

• 與舊版 WORKSPACE 系統相比，好處多多，有助於確保 Bazel 生態系統健康成長。

• 如果您的專案是其他專案的依附元件，遷移至 Bzlmod 可解除這些專案的遷移作業，並讓這些專案更輕鬆地依附您的專案。

• 如要使用日後的 Bazel 版本 (Bazel 9 必須使用)，就必須遷移至 Bzlmod。

如何遷移至 Bzlmod？

建議的遷移程序：

1. 使用遷移工具做為輔助工具，盡可能簡化遷移程序。請參閱「遷移工具」和「如何使用工具」部分。
2. 如果使用遷移工具後仍有錯誤，請手動解決。如要瞭解 WORKSPACE 和 MODULE.bazel 檔案中概念的主要差異，請參閱「WORKSPACE 與 Bzlmod」一節。

遷移工具

從 WORKSPACE 遷移至 Bzlmod 的過程通常很複雜，因此強烈建議使用遷移指令碼，這項輔助工具會自動執行許多步驟，協助您遷移外部依附元件管理系統。

核心功能

這個指令碼的主要功能如下：

• 收集依附元件資訊：分析專案的 WORKSPACE 檔案，找出指定建構目標使用的外部存放區。這個工具會使用 Bazel 的 experimental_repository_resolved_file 標記，產生包含這項資訊的 resolved_deps.py 檔案。
• 直接依附元件識別：使用 bazel query 判斷指定目標的直接依附元件是哪些存放區。
• Bzlmod 遷移：將相關 WORKSPACE 依附元件轉換為 Bzlmod 對等項目。這個過程分為兩步驟：
  1. 嘗試將所有已識別的直接依附元件導入 MODULE.bazel 檔案。
  2. 嘗試在啟用 Bzlmod 的情況下建構指定目標，然後反覆找出並修正可辨識的錯誤。由於第一個步驟可能缺少某些依附元件，因此需要執行這個步驟。
• 產生遷移報告：建立 migration_info.md 檔案，記錄遷移程序。這份報表會列出直接依附元件、產生的 Bzlmod 宣告，以及完成遷移可能需要的手動步驟。

遷移工具支援：

• Bazel 中央登錄檔提供的依附元件
• 使用者定義的自訂存放區規則
• [即將推出] 套件管理工具依附元件

重要事項：遷移工具會盡可能完成作業。請務必仔細檢查建議是否正確。

如何使用遷移工具

事前準備：

• 升級至最新的 Bazel 7 版本，這個版本可為 WORKSPACE 和 Bzlmod 提供強大的支援。

• 確認下列指令是否已針對專案的主要建構目標順利執行：

  bazel build --nobuild --enable_workspace --noenable_bzlmod <targets>
  

符合必要條件後，請執行下列指令來使用遷移工具：

# Clone the Bazel Central Registry repository
git clone https://github.com/bazelbuild/bazel-central-registry.git
cd bazel-central-registry

# Build the migration tool
bazel build //tools:migrate_to_bzlmod

# Create a convenient alias for the tool
alias migrate2bzlmod=$(realpath ./bazel-bin/tools/migrate_to_bzlmod)

# Navigate to your project's root directory and run the tool
cd <your workspace root>
migrate2bzlmod -t <your build targets>

WORKSPACE 與 Bzlmod

Bazel 的 WORKSPACE 和 Bzlmod 提供類似功能，但語法不同。本節說明如何從特定 WORKSPACE 功能遷移至 Bzlmod。

定義 Bazel 工作區的根目錄

WORKSPACE 檔案會標示 Bazel 專案的來源根目錄，這項責任在 Bazel 6.3 以上版本中，會由 MODULE.bazel 取代。如果 Bazel 版本低於 6.3，工作區根目錄中應該仍有 WORKSPACE 或 WORKSPACE.bazel 檔案，可能含有類似下列的註解：

• WORKSPACE

  # This file marks the root of the Bazel workspace.
  # See MODULE.bazel for external dependencies setup.
  

在 bazelrc 中啟用 Bzlmod

可讓您設定每次執行 Bazel 時套用的標記。.bazelrc如要啟用 Bzlmod，請使用 --enable_bzlmod 旗標，並將其套用至 common 指令，以便套用至每個指令：

• .bazelrc

  # Enable Bzlmod for every Bazel command
  common --enable_bzlmod
  

為工作區指定存放區名稱

• WORKSPACE

  workspace 函式用於指定工作區的存放區名稱。這樣一來，工作區中的目標 //foo:bar 就能以 @<workspace name>//foo:bar 參照。如未指定，工作區的預設存放區名稱為 __main__。

  ## WORKSPACE
  workspace(name = "com_foo_bar")
  

• Bzlmod

  建議您使用 //foo:bar 語法參照同一工作區中的目標，但不要使用 @<repo name>。但如果需要舊版語法，可以使用 module 函式指定的模組名稱做為存放區名稱。如果模組名稱與所需存放區名稱不同，可以使用 module 函式的 repo_name 屬性覆寫存放區名稱。

  ## MODULE.bazel
  module(
      name = "bar",
      repo_name = "com_foo_bar",
  )
  

以 Bazel 模組形式擷取外部依附元件

如果依附元件是 Bazel 專案，且也採用 Bzlmod，您應該可以將其視為 Bazel 模組。

• WORKSPACE

  使用 WORKSPACE 時，通常會使用 http_archive 或 git_repository 存放區規則，下載 Bazel 專案的來源。

  ## WORKSPACE
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
  
  http_archive(
      name = "bazel_skylib",
      urls = ["https://github.com/bazelbuild/bazel-skylib/releases/download/1.4.2/bazel-skylib-1.4.2.tar.gz"],
      sha256 = "66ffd9315665bfaafc96b52278f57c7e2dd09f5ede279ea6d39b2be471e7e3aa",
  )
  load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
  bazel_skylib_workspace()
  
  http_archive(
      name = "rules_java",
      urls = ["https://github.com/bazelbuild/rules_java/releases/download/6.1.1/rules_java-6.1.1.tar.gz"],
      sha256 = "76402a50ae6859d50bd7aed8c1b8ef09dae5c1035bb3ca7d276f7f3ce659818a",
  )
  load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains")
  rules_java_dependencies()
  rules_java_toolchains()
  

  如您所見，使用者需要從依附元件的巨集載入遞移依附元件，這是常見模式。假設 bazel_skylib 和 rules_java 都取決於 platform，則 platform 依附元件的確切版本取決於巨集的順序。

• Bzlmod

  使用 Bzlmod 時，只要依附元件位於 Bazel Central Registry 或自訂 Bazel 登錄檔，您就能透過 bazel_dep 指令依附該元件。

  ## MODULE.bazel
  bazel_dep(name = "bazel_skylib", version = "1.4.2")
  bazel_dep(name = "rules_java", version = "6.1.1")
  

  Bzlmod 會使用 MVS 演算法，以遞移方式解析 Bazel 模組依附元件。因此，系統會自動選取 platform 的最高必要版本。

以 Bazel 模組覆寫依附元件

做為根模組，您可以透過不同方式覆寫 Bazel 模組依附元件。

詳情請參閱覆寫一節。

您可以在 examples 存放區中找到一些使用範例。

使用模組擴充功能擷取外部依附元件

如果依附元件不是 Bazel 專案，或尚未在任何 Bazel 登錄檔中提供，您可以使用 use_repo_rule 或模組擴充功能導入。

• WORKSPACE

  使用 http_file 存放區規則下載檔案。

  ## WORKSPACE
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  
  http_file(
      name = "data_file",
      url = "http://example.com/file",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
  

• Bzlmod

  使用 Bzlmod 時，您可以在 MODULE.bazel 檔案中使用 use_repo_rule 指令，直接例項化存放區：

  ## MODULE.bazel
  http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  http_file(
      name = "data_file",
      url = "http://example.com/file",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
  

  這項功能實際上是透過模組擴充功能實作。如果您需要執行比叫用存放區規則更複雜的邏輯，也可以自行實作模組擴充功能。您需要將定義移至 .bzl 檔案，這樣在遷移期間，您也能在 WORKSPACE 和 Bzlmod 之間共用定義。

  ## repositories.bzl
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  def my_data_dependency():
      http_file(
          name = "data_file",
          url = "http://example.com/file",
          sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      )
  

  實作模組擴充功能，載入依附元件巨集。您可以在巨集的相同 .bzl 檔案中定義，但為了與舊版 Bazel 相容，建議在個別的 .bzl 檔案中定義。

  ## extensions.bzl
  load("//:repositories.bzl", "my_data_dependency")
  def _non_module_dependencies_impl(_ctx):
      my_data_dependency()
  
  non_module_dependencies = module_extension(
      implementation = _non_module_dependencies_impl,
  )
  

  如要讓根專案看得到存放區，請在 MODULE.bazel 檔案中宣告模組擴充功能和存放區的用法。

  ## MODULE.bazel
  non_module_dependencies = use_extension("//:extensions.bzl", "non_module_dependencies")
  use_repo(non_module_dependencies, "data_file")
  

使用模組擴充功能解決外部依附元件衝突

專案可以提供巨集，根據呼叫端的輸入內容導入外部存放區。但如果依附元件圖中有多個呼叫端，且這些呼叫端造成衝突，該怎麼辦？

假設專案 foo 提供下列巨集，並以 version 做為引數。

## repositories.bzl in foo {:#repositories.bzl-foo}
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def data_deps(version = "1.0"):
    http_file(
        name = "data_file",
        url = "http://example.com/file-%s" % version,
        # Omitting the "sha256" attribute for simplicity
    )

• WORKSPACE

  您可以使用 WORKSPACE 從 @foo 載入巨集，並指定所需的資料依附元件版本。假設您有另一個依附元件 @bar，這個依附元件也依附於 @foo，但需要不同版本的資料依附元件。

  ## WORKSPACE
  
  # Introduce @foo and @bar.
  ...
  
  load("@foo//:repositories.bzl", "data_deps")
  data_deps(version = "2.0")
  
  load("@bar//:repositories.bzl", "bar_deps")
  bar_deps() # -> which calls data_deps(version = "3.0")
  

  在這種情況下，使用者必須仔細調整 WORKSPACE 中的巨集順序，才能取得所需版本。這是 WORKSPACE 最令人頭痛的問題之一，因為它並未提供解決依附元件的合理方式。

• Bzlmod

  使用 Bzlmod 時，專案 foo 的作者可以運用模組擴充功能解決衝突。舉例來說，假設在所有 Bazel 模組中，一律選取資料依附元件的最高必要版本是合理的。

  ## extensions.bzl in foo
  load("//:repositories.bzl", "data_deps")
  
  data = tag_class(attrs={"version": attr.string()})
  
  def _data_deps_extension_impl(module_ctx):
      # Select the maximal required version in the dependency graph.
      version = "1.0"
      for mod in module_ctx.modules:
          for data in mod.tags.data:
              version = max(version, data.version)
      data_deps(version)
  
  data_deps_extension = module_extension(
      implementation = _data_deps_extension_impl,
      tag_classes = {"data": data},
  )
  

  ## MODULE.bazel in bar
  bazel_dep(name = "foo", version = "1.0")
  
  foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
  foo_data_deps.data(version = "3.0")
  use_repo(foo_data_deps, "data_file")
  

  ## MODULE.bazel in root module
  bazel_dep(name = "foo", version = "1.0")
  bazel_dep(name = "bar", version = "1.0")
  
  foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
  foo_data_deps.data(version = "2.0")
  use_repo(foo_data_deps, "data_file")
  

  在這種情況下，根模組需要資料版本 2.0，而其依附元件 bar 則需要 3.0。foo 中的模組擴充功能可以正確解決這項衝突，並自動選取資料依附元件的 3.0 版本。

整合第三方套件管理工具

如上一節所述，由於模組擴充功能提供從依附元件圖表收集資訊的方法，因此執行自訂邏輯來解析依附元件，並呼叫存放區規則來導入外部存放區，是規則作者強化規則集的好方法，可整合特定語言的套件管理工具。

請參閱模組擴充功能頁面，進一步瞭解如何使用模組擴充功能。

以下列出已採用 Bzlmod 從不同套件管理工具擷取依附元件的規則集：

• rules_jvm_external
• rules_go
• rules_python

如需整合虛擬套件管理員的簡短範例，請參閱 examples 存放區。

偵測主機上的工具鍊

當 Bazel 建構規則需要偵測主機上可用的工具鍊時，會使用存放區規則檢查主機，並以外部存放區的形式產生工具鍊資訊。

• WORKSPACE

  假設有下列存放區規則，可偵測殼層工具鍊。

  ## local_config_sh.bzl
  def _sh_config_rule_impl(repository_ctx):
      sh_path = get_sh_path_from_env("SH_BIN_PATH")
  
      if not sh_path:
          sh_path = detect_sh_from_path()
  
      if not sh_path:
          sh_path = "/shell/binary/not/found"
  
      repository_ctx.file("BUILD", """
  load("@bazel_tools//tools/sh:sh_toolchain.bzl", "sh_toolchain")
  sh_toolchain(
      name = "local_sh",
      path = "{sh_path}",
      visibility = ["//visibility:public"],
  )
  toolchain(
      name = "local_sh_toolchain",
      toolchain = ":local_sh",
      toolchain_type = "@bazel_tools//tools/sh:toolchain_type",
  )
  """.format(sh_path = sh_path))
  
  sh_config_rule = repository_rule(
      environ = ["SH_BIN_PATH"],
      local = True,
      implementation = _sh_config_rule_impl,
  )
  

  您可以在 WORKSPACE 中載入存放區規則。

  ## WORKSPACE
  load("//:local_config_sh.bzl", "sh_config_rule")
  sh_config_rule(name = "local_config_sh")
  

• Bzlmod

  使用 Bzlmod 時，您可以透過模組擴充功能導入相同存放區，這與上一節中導入 @data_file 存放區的方式類似。

  ## local_config_sh_extension.bzl
  load("//:local_config_sh.bzl", "sh_config_rule")
  
  sh_config_extension = module_extension(
      implementation = lambda ctx: sh_config_rule(name = "local_config_sh"),
  )
  

  接著在 MODULE.bazel 檔案中使用擴充功能。

  ## MODULE.bazel
  sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
  use_repo(sh_config_ext, "local_config_sh")
  

註冊工具鍊和執行平台

如最後一節所述，在導入存放區代管工具鍊資訊 (例如 local_config_sh) 後，您可能想註冊工具鍊。

• WORKSPACE

  您可以使用 WORKSPACE，透過下列方式註冊工具鍊。

  1. 您可以在 .bzl 檔案中註冊工具鍊，並在 WORKSPACE 檔案中載入巨集。

     ## local_config_sh.bzl
     def sh_configure():
         sh_config_rule(name = "local_config_sh")
         native.register_toolchains("@local_config_sh//:local_sh_toolchain")
     

     ## WORKSPACE
     load("//:local_config_sh.bzl", "sh_configure")
     sh_configure()
     

  2. 或者，直接在 WORKSPACE 檔案中註冊工具鍊。

     ## WORKSPACE
     load("//:local_config_sh.bzl", "sh_config_rule")
     sh_config_rule(name = "local_config_sh")
     register_toolchains("@local_config_sh//:local_sh_toolchain")
     

• Bzlmod

  使用 Bzlmod 時，register_toolchains 和 register_execution_platforms API 僅適用於 MODULE.bazel 檔案。您無法在模組擴充功能中呼叫 native.register_toolchains。

  ## MODULE.bazel
  sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
  use_repo(sh_config_ext, "local_config_sh")
  register_toolchains("@local_config_sh//:local_sh_toolchain")
  

在 WORKSPACE、WORKSPACE.bzlmod 和每個 Bazel 模組的 MODULE.bazel 檔案中註冊的工具鍊和執行平台，在工具鍊選取期間會依下列優先順序 (由高至低)：

1. 在根模組的 MODULE.bazel 檔案中註冊的工具鍊和執行平台。
2. 在 WORKSPACE 或 WORKSPACE.bzlmod 檔案中註冊的工具鍊和執行平台。
3. 由根模組的 (遞移) 依附元件註冊的工具鍊和執行平台。
4. 未使用 WORKSPACE.bzlmod 時：在 WORKSPACE 後置字元中註冊的工具鍊。

介紹本機存放區

如果需要依附元件的本機版本進行偵錯，或是想將工作區中的目錄併入為外部存放區，您可能需要將依附元件做為本機存放區導入。

• WORKSPACE

  使用 WORKSPACE 時，可透過兩項原生存放區規則達成此目的：local_repository 和 new_local_repository。

  ## WORKSPACE
  local_repository(
      name = "rules_java",
      path = "/Users/bazel_user/workspace/rules_java",
  )
  

• Bzlmod

  使用 Bzlmod 時，您可以透過 local_path_override，以本機路徑覆寫模組。

  ## MODULE.bazel
  bazel_dep(name = "rules_java")
  local_path_override(
      module_name = "rules_java",
      path = "/Users/bazel_user/workspace/rules_java",
  )
  

  注意： 使用 local_path_override 時，您只能將本機目錄做為 Bazel 模組導入，也就是說，該目錄必須有 MODULE.bazel 檔案，且在解析依附元件時會考量其遞移依附元件。此外，所有模組覆寫指令只能由根模組使用。

  您也可以透過模組擴充功能導入本機存放區。 不過，您無法在模組擴充功能中呼叫 native.local_repository，目前我們正努力將所有原生存放區規則 Starlark 化 (請參閱 #18285 瞭解進度)。接著，您可以在模組擴充功能中呼叫對應的 Starlark local_repository。如果這是您的阻礙問題，實作自訂版本的 local_repository 存放區規則也很簡單。

繫結目標

WORKSPACE 中的 bind 規則已淘汰，Bzlmod 不支援這項規則。這項功能推出後，目標就能在特殊的 //external 套件中取得別名。所有依附於此項目的使用者都應遷移。

舉例來說

## WORKSPACE
bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

這樣一來，其他目標就能依附於 //external:openssl。如要遷移，請採取下列做法：

• 將所有 //external:openssl 用法替換為 @my-ssl//src:openssl-lib。

  • 提示：使用 bazel query --output=build --noenable_bzlmod --enable_workspace [target] 指令尋找目標的相關資訊。

• 或使用 alias 建構規則

  • 在套件 (例如 //third_party) 中定義下列目標

    ## third_party/BUILD
    alias(
        name = "openssl",
        actual = "@my-ssl//src:openssl-lib",
    )
    

  • 將所有 //external:openssl 用法替換為 //third_party:openssl。

擷取與同步

擷取和同步處理指令可用於在本機下載外部存放區，並保持最新狀態。有時也會在擷取建構作業所需的所有存放區後，使用 --nofetch 標記離線建構。

• WORKSPACE

  同步會強制擷取所有存放區或特定設定的存放區集，而擷取只用於擷取特定目標。

• Bzlmod

  同步指令已不適用，但擷取提供各種選項。您可以擷取目標、存放區、一組已設定的存放區，或參與依附元件解析和模組擴充功能的所有存放區。擷取結果會快取，如要強制擷取，必須在擷取程序中加入 --force 選項。

手動遷移

本節提供實用資訊和指南，協助您手動遷移 Bzlmod。如要瞭解更自動化的遷移程序，請參閱「建議的遷移程序」一節。

瞭解 WORKSPACE 中的依附元件

遷移的第一步是瞭解您有哪些依附元件。由於遞移依附元件通常會透過 *_deps 巨集載入，因此可能難以判斷 WORKSPACE 檔案中導入了哪些確切的依附元件。

使用工作區解析的檔案檢查外部依附元件

幸好，--experimental_repository_resolved_file 標記可以派上用場。這個標記基本上會為上一個 Bazel 指令中擷取的所有外部依附元件產生「鎖定檔案」。詳情請參閱這篇網誌文章。

使用方法有兩種：

1. 擷取建構特定目標所需的外部依附元件資訊。

   bazel clean --expunge
   bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
   

2. 擷取 WORKSPACE 檔案中定義的所有外部依附元件資訊。

   bazel clean --expunge
   bazel sync --experimental_repository_resolved_file=resolved.bzl
   

   您可以使用 bazel sync 指令擷取 WORKSPACE 檔案中定義的所有依附元件，包括：

   • bind用量
   • register_toolchains和register_execution_platforms用量

   不過，如果專案是跨平台，bazel 同步作業可能會在特定平台上中斷，因為部分存放區規則可能只會在支援的平台上正確執行。

執行指令後，resolved.bzl 檔案中應該會顯示外部依附元件的資訊。

使用 bazel query 檢查外部依附元件

您可能也知道 bazel query 可用於檢查存放區規則，

bazel query --output=build //external:<repo name>

雖然更方便且速度快得多，但 bazel 查詢可能會謊報外部依附元件版本，因此請謹慎使用！使用 Bzlmod 查詢及檢查外部依附元件時，會用到新的子指令。

內建預設依附元件

如果您檢查 --experimental_repository_resolved_file 產生的檔案，會發現許多未在 WORKSPACE 中定義的依附元件。這是因為 Bazel 實際上會在使用者 WORKSPACE 檔案內容中加入前置字元和後置字元，以插入一些通常是原生規則 (例如 @bazel_tools、@platforms 和 @remote_java_tools) 所需的預設依附元件。使用 Bzlmod 時，這些依附元件會透過內建模組 bazel_tools 導入，這是所有其他 Bazel 模組的預設依附元件。

混合模式，可逐步遷移

Bzlmod 和 WORKSPACE 可以並存，因此您可以逐步將依附元件從 WORKSPACE 檔案遷移至 Bzlmod。

注意： 在實務上，於 WORKSPACE 中載入「*_deps」巨集通常會造成 Bzlmod 依附元件混淆，因此建議從 WORKSPACE.bzlmod 檔案開始，並避免使用巨集載入遞移依附元件。

WORKSPACE.bzlmod

在遷移期間，Bazel 使用者可能需要在啟用和未啟用 Bzlmod 的建構作業之間切換。導入 WORKSPACE.bzlmod 支援，讓程序更順暢。

WORKSPACE.bzlmod 的語法與 WORKSPACE 完全相同。啟用 Bzlmod 時，如果工作區根目錄中也有 WORKSPACE.bzlmod 檔案：

• WORKSPACE.bzlmod 會生效，且系統會忽略 WORKSPACE 的內容。
• 不會在 WORKSPACE.bzlmod 檔案中加入前置或後置字串。

使用 WORKSPACE.bzlmod 檔案可簡化遷移作業，原因如下：

• 停用 Bzlmod 時，系統會改為從原始 WORKSPACE 檔案擷取依附元件。
• 啟用 Bzlmod 後，您可以使用 WORKSPACE.bzlmod 更輕鬆地追蹤要遷移的其餘依附元件。

存放區瀏覽權限

Bzlmod 可控管特定存放區可見的其他存放區，詳情請參閱存放區名稱和嚴格依附元件。

下表摘要說明不同類型存放區的存放區可見度，並考量 WORKSPACE。

	從主要存放區	來自 Bazel 模組存放區	來自模組擴充功能存放區	從 WORKSPACE 存放區
主要存放區	顯示	如果根模組是直接依附元件	如果根模組是裝載模組擴充功能的模組的直接依附元件	顯示
Bazel 模組 repo	Direct deps	Direct deps	代管模組擴充功能的模組的直接依附元件	根模組的直接依附元件
模組擴充功能存放區	Direct deps	Direct deps	裝載模組擴充功能的模組直接依附元件 + 同一模組擴充功能產生的所有存放區	根模組的直接依附元件
WORKSPACE Repos	所有可見的	隱藏	隱藏	所有可見的

注意：如果是根模組，且存放區 @foo 是在 WORKSPACE 中定義，並在 MODULE.bazel 中也做為明顯存放區名稱使用，則 @foo 是指 MODULE.bazel 中導入的存放區。

注意：如果是模組擴充功能產生的存放區 @bar，且 @foo 是做為明顯存放區名稱使用，則 @foo 是指由相同模組擴充功能產生的另一個存放區，以及裝載模組擴充功能的模組直接依附元件。

@foo@bar

手動遷移程序

典型的 Bzlmod 遷移程序如下：

1. 瞭解 WORKSPACE 中的依附元件。
2. 在專案根層級新增空白的 MODULE.bazel 檔案。
3. 新增空白的 WORKSPACE.bzlmod 檔案，覆寫 WORKSPACE 檔案內容。
4. 啟用 Bzlmod 後建構目標，並檢查缺少哪個存放區。
5. 在已解決的依附元件檔案中，檢查遺失存放區的定義。
6. 透過模組擴充功能，以 Bazel 模組的形式導入缺少的依附元件，或將其保留在 WORKSPACE.bzlmod 中，以便稍後遷移。
7. 返回步驟 4 並重複執行，直到所有依附元件都可使用為止。

發布 Bazel 模組

如果您的 Bazel 專案是其他專案的依附元件，您可以將專案發布至 Bazel Central Registry。

如要在 BCR 中簽入專案，您需要專案的來源封存網址。建立來源封存時，請注意下列事項：

• 確認封存檔指向特定版本。

  BCR 只能接受已加上版本的來源封存檔，因為 Bzlmod 需要在依附元件解析期間進行版本比較。

• 確認封存網址穩定。

  Bazel 會透過雜湊值驗證封存內容，因此請確保下載檔案的總和檢查碼不會變更。如果網址來自 GitHub，請在發布頁面中建立並上傳發布封存檔。GitHub 不會保證隨選產生的來源封存檔的總和檢查碼。簡而言之，https://github.com/<org>/<repo>/releases/download/... 形式的網址視為穩定，https://github.com/<org>/<repo>/archive/... 則否。如需更多背景資訊，請參閱 GitHub 封存檢查碼 中斷。

• 確認來源樹狀結構遵循原始存放區的版面配置。

  如果您的存放區非常大，且您想建立大小縮減的發布封存檔 (方法是移除不必要的來源)，請務必確認移除後的來源樹狀結構是原始來源樹狀結構的子集。這樣一來，使用者就能更輕鬆地透過 archive_override 和 git_override，將模組覆寫為非發布版本。

• 在子目錄中加入測試最常見 API 的測試模組。

  測試模組是 Bazel 專案，在來源封存檔的子目錄中，有自己的 WORKSPACE 和 MODULE.bazel 檔案，依附於要發布的實際模組。應包含涵蓋最常見 API 的範例或一些整合測試。請參閱測試模組，瞭解如何設定。

準備好來源封存網址後，請按照 BCR 貢獻指南，透過 GitHub Pull Request 將模組提交至 BCR。

強烈建議為存放區設定「Publish to BCR」 GitHub 應用程式，自動將模組提交至 BCR。

最佳做法

本節列舉幾項最佳做法，可協助您更妥善地管理外部依附元件。

將目標分割成不同套件，避免擷取不必要的依附元件。

請參閱 #12835，瞭解測試的開發依附元件為何會強制擷取，導致建構目標時出現不必要的依附元件。這實際上並非 Bzlmod 專屬，但遵循這些做法可更輕鬆地正確指定開發依附元件。

指定開發依附元件

您可以將 dev_dependency 屬性設為 true，用於 bazel_dep 和 use_extension 指令，這樣這些指令就不會傳播至依附專案。做為根模組，您可以使用 --ignore_dev_dependency 旗標，確認目標是否仍可建構，且沒有開發依附元件和覆寫。

社群遷移進度

您可以查看 Bazel Central Registry，瞭解依附元件是否已可使用。否則，歡迎加入這項 GitHub 討論，投下贊成票或發布阻礙遷移作業的依附元件。

回報問題

請查看 Bazel GitHub 問題清單，瞭解 Bzlmod 已知問題。歡迎提交新問題或功能要求，協助您解決遷移作業的阻礙！