套件組態

bundle-config - 設定 Bundler 組態選項

bundle config list

bundle config [get] NAME

bundle config [set] NAME VALUE

bundle config unset NAME

說明

這個指令讓您可以與 Bundler 的組態系統互動。

Bundler 會依據以下順序載入組態設定

本機組態 (<project_root>/.bundle/config 或 $BUNDLE_APP_CONFIG/config)
環境變數 (ENV)
全域組態 (~/.bundle/config)
Bundler 預設組態

執行 bundle config list 會列印目前套件組態中所有 Bundler 組態的清單，以及這些組態設定在哪裡。

執行 bundle config get <name> 會列印該組態設定的值，以及設定在哪裡。

執行 bundle config set <name> <value> 預設會設定 本機 組態，如果從本機應用程式內執行，否則會設定 全域 組態。請參閱下列的 --local 和 --global 選項。

執行 bundle config set --local <name> <value> 會在本地應用程式的目錄中設定該組態。組態會儲存在 <project_root>/.bundle/config。如果設定了 BUNDLE_APP_CONFIG，組態會儲存在 $BUNDLE_APP_CONFIG/config。

執行 bundle config set --global <name> <value> 會將該組態設定為目前使用者執行所有套件組態時指定的值。組態會儲存在 ~/.bundle/config。如果已經設定了 name，將會覆寫 name，並會警告使用者。

執行 bundle config unset <name> 會刪除本機和全域來源中的組態。

執行 bundle config unset --global <name> 會僅從使用者組態中刪除組態。

執行 bundle config unset --local <name> 會僅從本機應用程式中刪除組態。

執行套件組態時設定 BUNDLE_IGNORE_CONFIG 環境變數，會讓它忽略所有組態。

記住選項

傳遞給 bundle install 或 Bundler 執行時期的旗標，例如 --path foo 或 --without production，會在指令之間記住並儲存在您本機應用程式的組態中 (通常是 ./.bundle/config)。

不過，這會在 Bundler 3 中變更，因此最好不要依賴此行為。如果必須記住這些選項，最好使用 bundle config 設定它們 (例如，bundle config set --local path foo)。

可以設定的選項為

bin: 建立目錄（預設為 ~/bin）並將任何可執行檔從 gem 放置在那裡。這些可執行檔在 Bundler 的內容中執行。如果使用，您可能會將此目錄新增到環境的 PATH 變數。例如，如果 rails gem 附帶 rails 可執行檔，此旗標將建立 bin/rails 可執行檔，以確保所有參考的相依性都將使用已套件化的 gem 來解析。
部署: 在部署模式中，Bundler 將「推出」套件以供 production 使用。如果您想要在 development 或 test 環境中啟用此選項，請仔細檢查。
僅: 僅安裝指定群組 gem 的空白分隔清單。
路徑: 安裝指定 gem 的位置。這預設為 Rubygems 的設定。Bundler 與 Rubygems 共享此位置，gem install ... 也會將 gem 安裝在那裡。因此，未設定 --path ... 的已安裝 gem 將透過呼叫 gem list 顯示。因此，安裝到其他位置的 gem 將不會列出。
不含: 在安裝期間略過 gem 參考的群組的空白分隔清單。
含: 在安裝期間包含 gem 參考的選用群組的空白分隔清單。

建置選項

您可以使用 bundle config 提供旗標給 Bundler，以便在 bundler 嘗試安裝特定 gem 時傳遞給 gem 安裝程式。

一個非常常見的範例，mysql gem，需要 Snow Leopard 使用者傳遞組態旗標給 gem install 以指定尋找 mysql_config 可執行檔的位置。

gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config

由於該可執行檔的特定位置可能會因機器而異，因此您可以逐機器指定這些旗標。

bundle config set --global build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config

在執行此指令後，每當 bundler 需要安裝 mysql gem 時，它將傳遞您指定的旗標。

組態金鑰

bundler 中的組態金鑰有兩種形式：正規形式和環境變數形式。

例如，傳遞 --without 旗標給 bundle install(1) 會阻止 Bundler 安裝 Gemfile(5) 中指定的特定群組。Bundler 會在 app/.bundle/config 中保留此值，以便呼叫 Bundler.setup 不會嘗試從您未安裝的 Gemfile 中尋找 gem。此外，後續呼叫 bundle install(1) 會記住此設定並略過那些群組。

此組態的正規形式為 "without"。若要將正規形式轉換為環境變數形式，請將其大寫，並加上前綴 BUNDLE_。"without" 的環境變數形式為 BUNDLE_WITHOUT。

設定環境變數時，組態金鑰中的任何句點都必須替換成兩個底線。組態金鑰 local.rack 會變成環境變數 BUNDLE_LOCAL__RACK。

可用金鑰清單

以下列出所有組態金鑰及其用途。您可以在 bundle install(1) 中進一步了解其操作。

allow_deployment_source_credential_changes (BUNDLE_ALLOW_DEPLOYMENT_SOURCE_CREDENTIAL_CHANGES)：在部署模式中，允許變更寶石來源的憑證。例如：https://some.host.com/gems/path/ -> https://user_name:password@some.host.com/gems/path
allow_offline_install (BUNDLE_ALLOW_OFFLINE_INSTALL)：允許 Bundler 在沒有網路存取權的情況下安裝時使用快取資料。
auto_clean_without_path (BUNDLE_AUTO_CLEAN_WITHOUT_PATH)：在未設定明確 path 且 Bundler 未安裝到系統寶石中時，在安裝後自動執行 bundle clean。
auto_install (BUNDLE_AUTO_INSTALL)：在缺少寶石時自動執行 bundle install。
bin (BUNDLE_BIN)：將套件中寶石的可執行檔安裝到指定的目錄。預設為 false。
cache_all (BUNDLE_CACHE_ALL)：快取所有寶石，包括路徑和 git 寶石。這需要在 bundler 1 和 bundler 2 中明確設定，但會是 bundler 3 的預設值。
cache_all_platforms (BUNDLE_CACHE_ALL_PLATFORMS)：快取所有平台的寶石。
cache_path (BUNDLE_CACHE_PATH)：執行 bundle package 時 bundler 會將快取寶石放置的目錄，以及 bundler 在安裝寶石時會尋找的目錄。預設為 vendor/cache。
clean (BUNDLE_CLEAN)：Bundler 是否應在 bundle install 之後自動執行 bundle clean。
console (BUNDLE_CONSOLE)：bundle console 啟動的控制台。預設為 irb。
default_install_uses_path (BUNDLE_DEFAULT_INSTALL_USES_PATH)：沒有明確 --path 參數的 bundle install 是否預設安裝寶石在 .bundle 中。
deployment (BUNDLE_DEPLOYMENT)：不允許變更 Gemfile。當 Gemfile 已變更且鎖定檔尚未更新時，執行 Bundler 指令會遭到封鎖。
disable_checksum_validation (BUNDLE_DISABLE_CHECKSUM_VALIDATION)：即使寶石與 RubyGems 提供的檢查碼不符，仍允許安裝寶石。
disable_exec_load (BUNDLE_DISABLE_EXEC_LOAD)：停止 Bundler 使用 load 在 bundle exec 中啟動執行中的可執行檔。
disable_local_branch_check (BUNDLE_DISABLE_LOCAL_BRANCH_CHECK)：允許 Bundler 使用本機 git 覆寫，而 Gemfile 中未指定分支。
disable_local_revision_check (BUNDLE_DISABLE_LOCAL_REVISION_CHECK)：允許 Bundler 使用本機 git 覆寫，而無需檢查鎖定檔中存在的版本是否存在於儲存庫中。
disable_shared_gems (BUNDLE_DISABLE_SHARED_GEMS)：停止 Bundler 存取安裝到 RubyGems 正常位置的寶石。
disable_version_check (BUNDLE_DISABLE_VERSION_CHECK)：停止 Bundler 檢查 rubygems.org 上是否有較新的 Bundler 版本可用。
force_ruby_platform (BUNDLE_FORCE_RUBY_PLATFORM)：忽略目前電腦的平台，僅安裝 ruby 平台寶石。因此，具有原生擴充功能的寶石將從來源編譯。
frozen (BUNDLE_FROZEN)：禁止變更 Gemfile。當 Gemfile 已變更且鎖定檔尚未更新時，執行 Bundler 指令將遭到封鎖。使用 --deployment 時，預設為 true。
gem.github_username (BUNDLE_GEM__GITHUB_USERNAME)：設定 GitHub 使用者名稱或組織，以便透過 bundle gem 指令建立新寶石時，使用在 README 檔案中。可透過傳遞明確的 --github-username 旗標給 bundle gem 來覆寫。
gem.push_key (BUNDLE_GEM__PUSH_KEY)：使用具有私人 gemstash 伺服器的 rake release 指令時，設定 gem push 的 --key 參數。
gemfile (BUNDLE_GEMFILE)：bundler 應作為 Gemfile 使用的檔案名稱。此檔案的位置也設定專案的根目錄，用於解析 Gemfile 中的相對路徑，以及其他事項。預設情況下，bundler 將從目前的工作目錄向上搜尋，直到找到 Gemfile。
global_gem_cache (BUNDLE_GLOBAL_GEM_CACHE)：Bundler 是否應將所有寶石快取為全域，而不是安裝到 Ruby 安裝的本機。
ignore_funding_requests (BUNDLE_IGNORE_FUNDING_REQUESTS)：設定後，不會列印任何資金請求。
ignore_messages (BUNDLE_IGNORE_MESSAGES)：設定後，不會列印任何安裝後訊息。若要讓單一寶石保持靜默，請使用點號表示法，例如 ignore_messages.httparty true。
init_gems_rb (BUNDLE_INIT_GEMS_RB)：執行 bundle init 時，產生 gems.rb 而不是 Gemfile。
jobs (BUNDLE_JOBS)：Bundler 可以並行安裝的寶石數量。預設為可用的處理器數量。
no_install (BUNDLE_NO_INSTALL)：bundle package 是否應略過安裝 gem。
no_prune (BUNDLE_NO_PRUNE)：Bundler 在快取時是否應保留過時的 gem，而不進行精簡。
only (BUNDLE_ONLY)：僅安裝指定群組 gem 的群組清單，各群組以空格分隔。
path (BUNDLE_PATH)：您的套件中所有 gem 的磁碟位置，不論 $GEM_HOME 或 $GEM_PATH 的值為何。bundle install 會安裝找不到此位置的套件 gem。預設為 Gem.dir。使用 --deployment 時，預設為 vendor/bundle。
path.system (BUNDLE_PATH__SYSTEM)：Bundler 是否會將 gem 安裝到預設系統路徑 (Gem.dir)。
path_relative_to_cwd (BUNDLE_PATH_RELATIVE_TO_CWD) 使 --path 相對於 CWD，而非 Gemfile。
plugins (BUNDLE_PLUGINS)：啟用 Bundler 的實驗性外掛系統。
prefer_patch (BUNDLE_PREFER_PATCH)：更新期間優先僅更新到下一個修補程式版本。使 bundle update 呼叫等於 bundler update --patch。
print_only_version_number (BUNDLE_PRINT_ONLY_VERSION_NUMBER)：僅從 bundler --version 列印版本號碼。
redirect (BUNDLE_REDIRECT)：允許網路要求的重新導向次數。預設為 5。
retry (BUNDLE_RETRY)：重試失敗網路要求的次數。預設為 3。
setup_makes_kernel_gem_public (BUNDLE_SETUP_MAKES_KERNEL_GEM_PUBLIC)：讓 Bundler.setup 使 Kernel#gem 方法公開，即使 RubyGems 將其宣告為私人。
shebang (BUNDLE_SHEBANG)：應為產生的 binstub 呼叫的程式名稱。預設為用於產生 binstub 的 ruby 安裝名稱。
silence_deprecations (BUNDLE_SILENCE_DEPRECATIONS)：Bundler 是否應對下一個主要版本中將變更的行為，取消不建議使用的警告。
silence_root_warning (BUNDLE_SILENCE_ROOT_WARNING)：取消 Bundler 在以 root 安裝 gem 時列印的警告。
ssl_ca_cert (BUNDLE_SSL_CA_CERT)：指定 CA 憑證檔案或包含 PEM 格式中多個受信任 CA 憑證的資料夾的路徑。
ssl_client_cert (BUNDLE_SSL_CLIENT_CERT)：指定包含 PEM 格式中 X.509 憑證和金鑰的指定檔案的路徑。
ssl_verify_mode (BUNDLE_SSL_VERIFY_MODE)：Bundler 在進行 HTTPS 要求時使用的 SSL 驗證模式。預設為驗證同儕。
system_bindir (BUNDLE_SYSTEM_BINDIR)：RubyGems 安裝 binstubs 的位置。預設為 Gem.bindir。
timeout (BUNDLE_TIMEOUT)：網路要求逾時前的允許秒數。預設為 10。
update_requires_all_flag (BUNDLE_UPDATE_REQUIRES_ALL_FLAG)：當應更新所有內容時，需要傳遞 --all 給 bundle update，並禁止不傳遞任何選項給 bundle update。
user_agent (BUNDLE_USER_AGENT)：Bundler 在 API 要求中包含的客製化使用者代理片段。
version (BUNDLE_VERSION)：在 Bundler 環境下執行時要使用的 Bundler 版本。預設為 lockfile。您也可以指定 system 或 x.y.z。lockfile 將使用在 Gemfile.lock 中指定的 Bundler 版本，system 將使用 Bundler 的系統版本，而 x.y.z 將使用指定的 Bundler 版本。
with (BUNDLE_WITH)：Bundler 應安裝其 gem 的群組的 : 分隔清單。
without (BUNDLE_WITHOUT)：Bundler 不應安裝其 gem 的群組的 : 分隔清單。

一般來說，您應該透過對 bundle install(1) 或 bundle cache(1) 命令使用適用的旗標，為每個應用程式設定這些設定。

您可以透過環境變數或 bundle config 全域設定它們，無論哪一種對您的設定較佳。如果您同時使用兩種方式，環境變數將優先於全域設定。

本機 Git 儲存庫

Bundler 也允許您使用本機 git 儲存庫，而不是使用遠端版本。這可透過設定本機覆寫來達成

bundle config set --local local.GEM_NAME /path/to/local/git/repository

例如，為了使用本機 Rack 儲存庫，開發人員可以呼叫

bundle config set --local local.rack ~/Work/git/rack

現在，系統將使用本機覆寫，而不是查看遠端 git 儲存庫。與路徑來源類似，每次本機 git 儲存庫變更時，Bundler 都會自動擷取變更。這表示本機 git 儲存庫中的提交會將 Gemfile.lock 中的版本更新為本機 git 儲存庫版本。這需要與 git 子模組一樣的注意。在推送到遠端之前，您需要確保已推送本機覆寫，否則您可能會指向僅存在於您的本機電腦中的提交。您也需要 CGI 轉譯您的使用者名稱和密碼。

Bundler 會執行許多檢查，以確保開發人員不會使用無效的參考。特別是，我們強制開發人員在 Gemfile 中指定分支，才能使用此功能。如果 Gemfile 中指定的的分支與本機 git 儲存庫中的目前分支不符，Bundler 將會中止。這可確保開發人員始終使用正確的分支，並防止意外鎖定到不同的分支。

最後，Bundler 也會確保 Gemfile.lock 中的目前版本存在於本機 git 儲存庫中。這樣做是為了強制 Bundler 擷取遠端中的最新變更。

寶石來源的鏡像

Bundler 支援使用鏡像覆寫寶石來源。這讓你可以將 rubygems.org 設定為 Gemfile 中的寶石來源，同時仍使用你的鏡像來擷取寶石。

bundle config set --global mirror.SOURCE_URL MIRROR_URL

例如，要使用託管在 https://example.org 的 https://rubygems.org 鏡像

bundle config set --global mirror.https://rubygems.org https://example.org

每個鏡像也提供備用逾時設定。如果鏡像在備用逾時內沒有回應，Bundler 會嘗試使用原始伺服器，而不是鏡像。

bundle config set --global mirror.SOURCE_URL.fallback_timeout TIMEOUT

例如，要在 3 秒後備回到 rubygems.org

bundle config set --global mirror.https://rubygems.org.fallback_timeout 3

預設備用逾時為 0.1 秒，但目前設定只能接受整秒（例如 1、15 或 30）。

寶石來源的認證資訊

Bundler 允許你為任何寶石來源設定認證資訊，這能讓你避免將機密資訊放入 Gemfile 中。

bundle config set --global SOURCE_HOSTNAME USERNAME:PASSWORD

例如，要儲存使用者 claudette 的認證資訊，以用於 gems.longerous.com 的寶石來源，你可以執行

bundle config set --global gems.longerous.com claudette:s00pers3krit

或者你可以像這樣設定認證資訊為環境變數

export BUNDLE_GEMS__LONGEROUS__COM="claudette:s00pers3krit"

對於具有 HTTP(S) URL 的 git 來源的寶石，你可以這樣指定認證資訊

bundle config set --global https://github.com/rubygems/rubygems.git username:password

或者你可以像這樣設定認證資訊為環境變數

export BUNDLE_GITHUB__COM=username:password

這對於 GitHub 等主機上的私人儲存庫特別有用，你可以在其中使用個人 OAuth 令牌

export BUNDLE_GITHUB__COM=abcd0123generatedtoken:x-oauth-basic

請注意，任何設定的認證資訊都會被 bundle config list 或 bundle config get 等資訊性指令刪除，除非你使用 --parseable 旗標。這是為了避免在複製貼上 bundler 輸出時意外洩漏認證資訊。

另外請注意，為了保證有效的環境變數名稱和有效的主機名稱之間的合理對應，bundler 會進行以下轉換

主機名稱中的任何 - 字元都會對應到環境變數中的三個底線 (___)。
主機名稱中的任何 . 字元都會對應到環境變數中的兩個底線 (__)。

這表示如果你有一個名為 my.gem-host.com 的寶石伺服器，你將需要使用 BUNDLE_MY__GEM___HOST__COM 變數來透過 ENV 為其設定認證。

設定 Bundler 目錄

Bundler 的 home、config、cache 和 plugin 目錄能夠透過環境變數進行設定。Bundler 的 home 目錄的預設位置為 ~/.bundle，所有目錄預設都會繼承自此目錄。以下是可用的環境變數及其預設值

BUNDLE_USER_HOME : $HOME/.bundle
BUNDLE_USER_CACHE : $BUNDLE_USER_HOME/cache
BUNDLE_USER_CONFIG : $BUNDLE_USER_HOME/config
BUNDLE_USER_PLUGIN : $BUNDLE_USER_HOME/plugin