bundle config

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 将打印当前 bundle 的所有 Bundler 配置列表，以及配置设置的位置。

执行 bundle config get <name> 将打印该配置设置的值，以及设置的位置。

执行 bundle config set <name> <value> 默认情况下，如果从本地应用程序中执行，则设置 local 配置，否则将设置 global 配置。请参阅下面的 --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 设置该配置为指定的值。配置将存储在 ~/.bundle/config 中。如果 name 已经设置，name 将被覆盖，用户将收到警告。

执行 bundle config unset <name> 将删除本地和全局来源中的配置。

执行 bundle config unset --global <name> 将仅从用户配置中删除配置。

执行 bundle config unset --local <name> 将仅从本地应用程序中删除配置。

如果设置了 BUNDLE_IGNORE_CONFIG 环境变量，则执行 bundle 将导致它忽略所有配置。

记住选项

传递给 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 提供传递给 gem 安装程序的标志，每次 bundler 尝试安装特定 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): 在部署模式下，允许更改 gem 源的凭据。例如：https://some.host.com/gems/path/ -> https://user_name:[email protected]/gems/path
allow_offline_install (BUNDLE_ALLOW_OFFLINE_INSTALL): 允许 Bundler 在没有网络连接的情况下使用缓存数据进行安装。
auto_clean_without_path (BUNDLE_AUTO_CLEAN_WITHOUT_PATH): 当没有显式设置 path 并且 Bundler 没有安装到系统 gem 时，在安装完成后自动运行 bundle clean。
auto_install (BUNDLE_AUTO_INSTALL): 当 gem 丢失时，自动运行 bundle install。
bin (BUNDLE_BIN): 将 gem 中的可执行文件安装到指定的目录。默认值为 false。
cache_all (BUNDLE_CACHE_ALL): 缓存所有 gem，包括路径和 git gem。这需要在 bundler 1 和 bundler 2 上显式配置，但在 bundler 3 上将是默认值。
cache_all_platforms (BUNDLE_CACHE_ALL_PLATFORMS): 缓存所有平台的 gem。
cache_path (BUNDLE_CACHE_PATH): Bundler 在运行 bundle package 时将缓存的 gem 放置在该目录中，并且 Bundler 在安装 gem 时会在该目录中查找。默认值为 vendor/cache。
clean (BUNDLE_CLEAN): 是否在 bundle install 之后自动运行 bundle clean。
console (BUNDLE_CONSOLE): bundle console 启动的控制台。默认值为 irb。
default_install_uses_path (BUNDLE_DEFAULT_INSTALL_USES_PATH): 是否在没有显式 --path 参数的情况下，bundle install 默认将 gem 安装到 .bundle 中。
deployment (BUNDLE_DEPLOYMENT): 禁止更改 Gemfile。当 Gemfile 发生更改并且 lockfile 未更新时，将阻止运行 Bundler 命令。
disable_checksum_validation (BUNDLE_DISABLE_CHECKSUM_VALIDATION): 即使 gem 与 RubyGems 提供的校验和不匹配，也允许安装 gem。
disable_exec_load (BUNDLE_DISABLE_EXEC_LOAD): 阻止 Bundler 在 bundle exec 中使用 load 在进程内启动可执行文件。
disable_local_branch_check (BUNDLE_DISABLE_LOCAL_BRANCH_CHECK): 允许 Bundler 使用本地 git 覆盖，而无需在 Gemfile 中指定分支。
disable_local_revision_check (BUNDLE_DISABLE_LOCAL_REVISION_CHECK): 允许 Bundler 使用本地 git 覆盖，而无需检查 lockfile 中的修订版本是否在存储库中存在。
disable_shared_gems (BUNDLE_DISABLE_SHARED_GEMS): 阻止 Bundler 访问安装到 RubyGems 正常位置的 gem。
disable_version_check (BUNDLE_DISABLE_VERSION_CHECK): 阻止 Bundler 检查 rubygems.org 上是否有更新的 Bundler 版本可用。
force_ruby_platform (BUNDLE_FORCE_RUBY_PLATFORM): 忽略当前机器的平台，只安装 ruby 平台 gem。因此，具有本机扩展的 gem 将从源代码编译。
frozen (BUNDLE_FROZEN): 禁止更改 Gemfile。当 Gemfile 发生更改并且 lockfile 未更新时，将阻止运行 Bundler 命令。当使用 --deployment 时，默认值为 true。
gem.github_username (BUNDLE_GEM__GITHUB_USERNAME): 设置一个 GitHub 用户名或组织，在使用 bundle gem 命令创建新 gem 时，将其用于 README 文件。可以通过向 bundle gem 传递显式的 --github-username 标志来覆盖它。
gem.push_key (BUNDLE_GEM__PUSH_KEY): 在使用 rake release 命令和私有 gemstash 服务器时，为 gem push 设置 --key 参数。
gemfile (BUNDLE_GEMFILE): Bundler 应该用作 Gemfile 的文件名称。此文件的路径也设置了项目的根目录，该目录用于解析 Gemfile 中的相对路径，以及其他用途。默认情况下，Bundler 将从当前工作目录向上搜索，直到找到 Gemfile。
global_gem_cache (BUNDLE_GLOBAL_GEM_CACHE): 是否让 Bundler 将所有 gem 缓存到全局，而不是本地安装 Ruby 的位置。
ignore_funding_requests (BUNDLE_IGNORE_FUNDING_REQUESTS): 设置后，不会打印任何资助请求。
ignore_messages (BUNDLE_IGNORE_MESSAGES): 设置后，不会打印任何安装后的消息。要静默单个 gem，请使用点符号，例如 ignore_messages.httparty true。
init_gems_rb (BUNDLE_INIT_GEMS_RB): 在运行 bundle init 时生成 gems.rb 而不是 Gemfile。
jobs (BUNDLE_JOBS): Bundler 可以并行安装的 gem 数量。默认为可用处理器的数量。
no_install (BUNDLE_NO_INSTALL): bundle package 是否应该跳过安装 gem。
no_prune (BUNDLE_NO_PRUNE): 缓存时，Bundler 是否应该保留过时的 gem。
only (BUNDLE_ONLY): 要安装的组的空格分隔列表，仅安装指定组的 gem。
path (BUNDLE_PATH): 磁盘上的位置，无论 $GEM_HOME 或 $GEM_PATH 的值如何，您的捆绑包中的所有 gem 都将位于该位置。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

现在，Bundler 将使用本地覆盖，而不是检出远程 git 仓库。与路径源类似，每次本地 git 仓库发生更改时，Bundler 都会自动获取更改。这意味着本地 git 仓库中的提交将更新 Gemfile.lock 中的修订版本到本地 git 仓库修订版本。这需要与 git 子模块相同的关注。在推送到远程之前，您需要确保已推送本地覆盖，否则您可能会指向仅存在于本地机器上的提交。您还需要对用户名和密码进行 CGI 转义。

Bundler 进行许多检查以确保开发人员不会使用无效的引用。特别是，我们强制开发人员在 Gemfile 中指定一个分支才能使用此功能。如果 Gemfile 中指定的分支与本地 git 仓库中的当前分支不匹配，Bundler 将中止。这确保开发人员始终针对正确的分支工作，并防止意外锁定到不同的分支。

最后，Bundler 还确保 Gemfile.lock 中的当前修订版存在于本地 git 仓库中。通过这样做，Bundler 强制您获取远程仓库中的最新更改。

Gem 源的镜像

Bundler 支持使用镜像覆盖 gem 源。这允许您在 Gemfile 中配置 rubygems.org 作为 gem 源，同时仍然使用您的镜像来获取 gem。

bundle config set --global mirror.SOURCE_URL MIRROR_URL

例如，要使用 https://rubygems.org.cn 的镜像，该镜像托管在 https://example.org

bundle config set --global mirror.https://rubygems.org.cn 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.cn.fallback_timeout 3

默认回退超时时间为 0.1 秒，但该设置目前只能接受整秒（例如，1、15 或 30）。

Gem 源的凭据

Bundler 允许您为任何 gem 源配置凭据，这使您无需将机密信息放入 Gemfile 中。

bundle config set --global SOURCE_HOSTNAME USERNAME:PASSWORD

例如，要保存 gems.longerous.com 上的 gem 源的用户 claudette 的凭据，您需要运行

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

或者您可以像这样将凭据设置为环境变量

export BUNDLE_GEMS__LONGEROUS__COM="claudette:s00pers3krit"

对于具有带有 HTTP(S) URL 的 git 源的 gem，您可以像这样指定凭据

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的 gem 服务器，则需要使用BUNDLE_MY__GEM___HOST__COM变量通过 ENV 配置其凭据。

配置 Bundler 目录

Bundler 的主目录、配置目录、缓存目录和插件目录可以通过环境变量进行配置。Bundler 主目录的默认位置是~/.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