config

Delphi源码 • 2025-08-15

config

概括

config可帮助您以简单可用的方式轻松管理特定环境设置。

特征

  • 简单的yaml config文件
  • config文件支持ERB
  • config文件支持继承和多个环境
  • 通过方便的对象成员表示法访问config信息
  • 支持多级设置（ Settings.group.subgroup.setting ）
  • 委托代码时忽略了本地开发人员设置

兼容性

当前版本支持并对以下解释器和框架进行了测试：

  • 口译员
    • Ruby >= 2.6
    • jruby >= 9.2
    • Truffleruby >= 19.3
  • 应用框架
    • 导轨>= 5.2
    • 帕德里诺
    • 辛纳屈

对于Ruby 2.0至2.3或Rails 3至4.1使用此宝石的1.x版本。对于较旧版本的导轨或Ruby使用应用程序config 。

对于Ruby 2.4或2.5或Rails 4.2或5.1 5.0此宝石的3.x版本。

安装

安装在导轨上

将gem ' config '添加到您的Gemfile并运行bundle install以安装它。然后运行

 rails g config :install

将生成自定义的config文件config /initializers/ config .rb和默认设置文件集：

config/settings.yml config /settings.local.yml config /settings/development.yml config /settings/production.yml config /settings/test.yml">
 config /settings.yml
config /settings.local.yml
config /settings/development.yml
config /settings/production.yml
config /settings/test.yml

您现在可以编辑它们以适应您的需求。

注意：默认情况下， config环境将与Rails环境（ Rails.env ）匹配。可以通过设置config .environment来更改。

安装在Padrino上

将宝石添加到您的Gemfile并运行bundle install以安装它。然后编辑app.rb并注册config 

 register config

安装在Sinatra上

将宝石添加到您的Gemfile并运行bundle install以安装它。之后，需要在您的应用中注册config并将其赋予根，以便它可以找到config文件。 

 set :root , File . dirname ( __FILE__ )
register config

安装其他红宝石项目

将宝石添加到您的Gemfile并运行bundle install以安装它。然后在您的config ure块中手动初始化config 。

config .setting_files("/path/to/ config _root", "your_project_environment"))">
 config . load_and_set_settings ( config . setting_files ( "/path/to/ config _root" , "your_project_environment" ) )

如果您只想给出一些YML路径以从您的config块中手动初始化config 。 

 config . load_and_set_settings ( "/path/to/yaml1" , "/path/to/yaml2" , ... )

访问设置对象

安装GEM后， Settings对象将在全球上可用，默认情况下将从下面列出的文件中编译。在列表中较低的文件中定义的设置更高。

config/settings.yml config /settings/#{environment}.yml config /environments/#{environment}.yml config /settings.local.yml config /settings/#{environment}.local.yml config /environments/#{environment}.local.yml">
 config /settings.yml
config /settings/#{environment}.yml
config /environments/#{environment}.yml

config /settings.local.yml
config /settings/#{environment}.local.yml
config /environments/#{environment}.local.yml

可以通过对象成员表示法访问条目： 

 Settings . my_ config _entry

支持嵌套条目： 

 Settings . my_section . some_entry

另外，如果您不知道需要提前访问的确切设置，也可以使用[]操作员。 

 # All the following are equivalent to Settings.my_section.some_entry
Settings . my_section [ :some_entry ]
Settings . my_section [ 'some_entry' ]
Settings [ :my_section ] [ :some_entry ]

重新加载设置

您可以随时通过运行Settings.reload! 。

重新加载设置和config文件

您还可以在运行时从不同的config文件重新加载Settings对象。

例如，在测试中，如果要测试生产设置，则可以：

config", "settings.yml").to_s, Rails.root.join(" config ", "settings", "#{Rails.env}.yml").to_s, Rails.root.join(" config ", "environments", "#{Rails.env}.yml").to_s )">
 Rails . env = "production"
Settings . reload_from_files (
  Rails . root . join ( " config " , "settings.yml" ) . to_s ,
  Rails . root . join ( " config " , "settings" , " #{ Rails . env } .yml" ) . to_s ,
  Rails . root . join ( " config " , "environments" , " #{ Rails . env } .yml" ) . to_s
)

环境特定的config文件

您可以具有特定环境的config文件。特定环境config条目优先于公共config条目。

示例开发环境config文件： 

 #{Rails.root}/ config /environments/development.yml

示例生产环境config文件： 

 #{Rails.root}/ config /environments/production.yml

额外的来源

您可以在初始化期间加载额外的来源，通过设置extra_sources config uration选项。

config | config .extra_sources = [ 'path/to/extra_source.yml', # String: loads extra_source.yml { api_key: ENV['API_KEY'] }, # Hash: direct hash source MyCustomSource.new, # Object: custom source object that responds to `load` ] end">
 config . setup do | config |
  config . extra_sources = [
    'path/to/extra_source.yml' ,          # String: loads extra_source.yml
    { api_key : ENV [ 'API_KEY' ] } ,         # Hash: direct hash source
    MyCustomSource . new ,                  # Object: custom source object that responds to `load`
  ]
end

这也将覆盖主文件中相同的config条目。

开发人员特定的config文件

如果您想具有特定于计算机或开发环境的本地设置，则可以使用以下文件，这些文件自动是.gitignore ：

config", "settings.local.yml").to_s, Rails.root.join(" config ", "settings", "#{Rails.env}.local.yml").to_s, Rails.root.join(" config ", "environments", "#{Rails.env}.local.yml").to_s">
 Rails . root . join ( " config " , "settings.local.yml" ) . to_s ,
Rails . root . join ( " config " , "settings" , " #{ Rails . env } .local.yml" ) . to_s ,
Rails . root . join ( " config " , "environments" , " #{ Rails . env } .local.yml" ) . to_s

注意： file settings.local.yml不会加载在测试中，以防止本地config引起片状或非确定性测试。环境特定文件（例如settings/test.local.yml ）仍将加载以允许特定于测试的凭据。

在运行时添加资源

您可以在运行时添加新的YAML config文件。只是使用： 

 Settings . add_source! ( "/path/to/source.yml" )
Settings . reload!

这将使用给定的源文件，并使用其设置来覆盖任何以前的文件。

另一方面，您可以将YML文件预先列入config文件列表： 

 Settings . prepend_source! ( "/path/to/source.yml" )
Settings . reload!

这将与add_source相同，但是给定的YML文件将首先加载（而不是上一个），其设置将被任何其他config文件覆盖。如果要定义默认值，这特别有用。

我喜欢为Rails项目做的一件事是提供一个local.yml config文件。然后，我在config /initializers/add_local_ config .rb中创建一个新的initializer

config/settings/local.yml") Settings.reload!">
 Settings . add_source! ( " #{ Rails . root } / config /settings/local.yml" )
Settings . reload!

注意：这是一个示例用法，只需使用默认的本地文件settings.local.yml ， settings/#{Rails.env}.local.yml和environments/#{Rails.env}.local.yml用于您的开发人员特定的设置。

您还可以选择添加RAW HASH作为来源。一种用例可能是将设置存储在数据库或覆盖YML文件中内容的环境变量中。 

 Settings . add_source! ( { some_secret : ENV [ 'some_secret' ] } )
Settings . reload!

您可以通过hash来prepend_source!也是如此。

嵌入红宝石（ERB）

在YAML config文件中允许嵌入Ruby。默认情况下，将在加载时间对ERB进行评估，并且当evaluate_erb_in_yaml config设置为true 。

考虑以下两个config文件。

  • #{Rails.root}/ config /settings.yml 
 size : 1
server : google.com
  • #{Rails.root}/ config /environments/development.yml 
 size : 2
computed : <%= 1 + 2 + 3 %>
section :
  size : 3
  servers : [ {name: yahoo.com}, {name: amazon.com} ]

请注意，环境特定的config条目覆盖了共同条目。 

 Settings . size   # => 2
Settings . server # => google.com

注意嵌入式红宝石。 

 Settings . computed # => 6

请注意，即使在嵌套条目中也保持对象成员表示法。 

 Settings . section . size # => 3

注意数组表示法和对象成员表示法。 

 Settings . section . servers [ 0 ] . name # => yahoo.com
Settings . section . servers [ 1 ] . name # => amazon.com

config

有多个可用的config选项，但是您只能在应用程序初始化阶段进行config定义一次：

config | config .const_name = 'Settings' # ... end">
 config . setup do | config |
  config . const_name = 'Settings'
  # ...
end

在Rails中安装config后，您会发现自动生成的文件，其中包含位于config /initializers/ config .rb的默认config URATION。

一般的

  • const_name持有设置的对象的名称。默认： 'Settings'
  • evaluate_erb_in_yaml在YAML config文件中评估ERB。设置为False，如果config文件包含不应在加载时评估的ERB。默认值： true
  • file_name文件的名称存储在所有环境中访问的通用密钥。默认值： 'settings' - 位于config /settings.yml上
  • dir_name目录的名称存储特定于环境的文件。默认值： 'settings' - 位于config /settings/

合并定制

  • overwrite_arrays在先前加载的设置文件中找到的覆盖阵列。默认值： true
  • merge_hash_arrays从先前加载的设置文件中的数组内部的合并哈希。只有当overwrite_arrays = false时才有意义。默认值： false
  • knockout_prefix能够删除在较早加载的设置文件中设置的数组的元素。只有当overwrite_arrays = false时才有意义，否则数组设置将被默认情况下覆盖。默认值： nil
  • merge_nil_values合并config s时， nil值将覆盖现有值。默认值： true 。
config ::Options size=2, ...> c.size # => 2 c.merge!(size: nil) => #< config ::Options size=nil, ...> c.size # => nil">
 # merge_nil_values is true by default
c = config . load_files ( "./spec/fixtures/development.yml" ) # => #< config ::Options size=2, ...>
c . size # => 2
c . merge! ( size : nil ) => #< config ::Options size=nil, ...>
c . size # => nil
config | config .merge_nil_values = false end c = config .load_files("./spec/fixtures/development.yml") # => #< config ::Options size=2, ...> c.size # => 2 c.merge!(size: nil) => #< config ::Options size=nil, ...> c.size # => 2">
 # To reject nil values when merging settings:
config . setup do | config |
  config . merge_nil_values = false
end

c = config . load_files ( "./spec/fixtures/development.yml" ) # => #< config ::Options size=2, ...>
c . size # => 2
c . merge! ( size : nil ) => #< config ::Options size=nil, ...>
c . size # => 2

检查深入合并以获取更多详细信息。

验证

使用Ruby 2.1或更新的情况，您可以选择使用Dry -Rb来定义架构或合同（在config -2.1中添加）以验证特定config值的存在（和类型）。一般而言，合同允许描述更复杂的验证，并在字段之间使用下降。

如果您提供验证选项（或两者），则将自动用于验证您的config 。如果验证失败，它将引起config ::Validation::Error其中包含有关模式和您的config之间所有不匹配的信息。

下面的两个示例均展示了如何确保config具有可选的email和youtube结构，并填充了api_key字段。合同添加了附加规则。

合同

利用干燥验证，您可以使用参数模式和规则创建合同：

configContract < Dry::Validation::Contract params do optional(:email).maybe(:str?) required(:youtube).schema do required(:api_key).filled end end rule(:email) do unless /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i.match?(value) key.failure('has invalid format') end end end config .setup do | config | config .validation_contract = config Contract.new end">
 class config Contract < Dry :: Validation :: Contract
  params do
    optional ( :email ) . maybe ( :str? )

    required ( :youtube ) . schema do
      required ( :api_key ) . filled
    end
  end

  rule ( :email ) do
    unless / \A [ \w + \- .]+@[a-z \d \- ]+( \. [a-z \d \- ]+)* \. [a-z]+ \z /i . match? ( value )
      key . failure ( 'has invalid format' )
    end
  end
end

config . setup do | config |
  config . validation_contract = config Contract . new
end

上面的示例添加了一个规则，以确保email通过将其与所提供的正则表达式匹配。

检查干燥验证以获取更多详细信息。

模式

您也可以使用干式式指定模式：

config | # ... config .schema do optional(:email).maybe(:str?) required(:youtube).schema do required(:api_key).filled end end end">
 config . setup do | config |
  # ...
  config . schema do
    optional ( :email ) . maybe ( :str? )

    required ( :youtube ) . schema do
      required ( :api_key ) . filled
    end
  end
end

检查Dry-Schema以获取更多详细信息。

缺少钥匙

对于示例设置文件： 

 size : 1
server : google.com

您可以使用key?及其别名has_key? ： 

 Settings . key? ( :path )
# => false
Settings . key? ( :server )
# => true

默认情况下，访问丢失的密钥返回nil ： 

 Settings . key? ( :path )
# => false
Settings . path
# => nil

这不是“错字安全”。要解决此问题，您可以config fail_on_missing选项：

config | config .fail_on_missing = true # ... end">
 config . setup do | config |
  config . fail_on_missing = true
  # ...
end

因此，在访问不存在的密钥时（类似于Hash#fetch行为），它将提出一个KeyError ： 

 Settings . path
# => raises KeyError: key not found: :path

环境变量

有关更多详细信息，请参见下面的部分。

使用环境变量

要加载来自ENV对象的环境变量，该变量将覆盖文件中定义的任何设置，请将use_env设置为config /initializers/ config .rb文件中的true：

config | config .const_name = 'Settings' config .use_env = true end">
 config . setup do | config |
  config . const_name = 'Settings'
  config . use_env = true
end

现在， config将从Env对象读取值到设置。对于上面的示例，它将寻找从Settings开始的键： 

 ENV [ 'Settings.section.size' ] = 1
ENV [ 'Settings.section.server' ] = 'google.com'

不过，它与数组无法使用。

使用环境变量同时为键分配“扁平”值和多级值。 

 # Raises an error when settings are loaded
ENV [ 'BACKEND_DATABASE' ] = 'development'
ENV [ 'BACKEND_DATABASE_USER' ] = 'postgres'

相反，在环境变量名称中指定相等深度的键： 

 ENV [ 'BACKEND_DATABASE_NAME' ] = 'development'
ENV [ 'BACKEND_DATABASE_USER' ] = 'postgres'

与Heroku合作

Heroku使用Env Object存储敏感设置。您无法将此类文件上传到Heroku，因为它的短暂文件系统会从每个实例刷新的git源中重新创建。与Heroku一起使用config只是将use_env var设置为true ，如上所述。

要将您的本地值上传到Heroku，您可以运行bundle exec rake config :heroku 。

微调

您可以自定义环境变量处理方式：

  • env_prefix （默认值： const_name ） - 仅加载Env变量以此前缀开头（case -simentive）
  • env_separator （默认值： '.' ） - 用作级别分离器的字符串 - 默认值的默认值.与Heroku合作良好，但是您可能需要将其更改为__的简易覆盖设置，其中可能不允许使用可变名称中的点（例如，bash）
  • env_converter （默认值:downcase ） - 如何处理变量名称：
    • nil - 没有改变
    • :downcase - 转换为较低的外壳
  • env_parse_values （默认值： true ） - 尝试将值解析为正确的类型（ Boolean ， Integer ， Float ， String ）

例如，给定以下环境： 

SETTINGS__SECTION__SERVER_SIZE=1
SETTINGS__SECTION__SERVER=google.com
SETTINGS__SECTION__SSL_ENABLED=false

以及以下config量：

config | config .use_env = true config .env_prefix = 'SETTINGS' config .env_separator = '__' config .env_converter = :downcase config .env_parse_values = true end">
 config . setup do | config |
  config . use_env = true
  config . env_prefix = 'SETTINGS'
  config . env_separator = '__'
  config . env_converter = :downcase
  config . env_parse_values = true
end

以下设置将可用： 

 Settings . section . server_size # => 1
Settings . section . server # => 'google.com'
Settings . section . ssl_enabled # => false

与AWS Secrets Manager合作

可以通过使用config ::Sources::EnvSource来解析存储在AWS Secrets Manager秘密中的变量。

例如，明文秘密看起来像这样： 

{
  "Settings.foo" : " hello " ,
  "Settings.bar" : " world " ,
}

为了加载这些设置，请从AWS Secrets Manager获取设置，将其授予JSON，将结果的Hash传递到新的EnvSource中，加载新来源和重新加载。

config secret_source = config ::Sources::EnvSource.new(secrets) Settings.add_source!(secret_source) Settings.reload!">
 # fetch secrets from AWS
client = Aws :: SecretsManager :: Client . new
response = client . get_secret_value ( secret_id : " #{ ENV [ 'ENVIRONMENT' ] } /my_application" )
secrets = JSON . parse ( response . secret_string )

# load secrets into config
secret_source = config :: Sources :: EnvSource . new ( secrets )
Settings . add_source! ( secret_source )
Settings . reload!

在这种情况下，将可用以下设置： 

 Settings . foo # => "hello"
Settings . bar # => "world"

默认情况下， EnvSource将使用env_prefix ， env_separator ， env_converter和env_parse_values使用config URATION，但是这些中的任何一个都可以在构造函数中覆盖。

config::Sources::EnvSource.new(secrets, prefix: 'My config ', separator: '__', converter: nil, parse_values: false)">
 secret_source = config :: Sources :: EnvSource . new ( secrets ,
                                               prefix : 'My config ' ,
                                               separator : '__' ,
                                               converter : nil ,
                                               parse_values : false )

贡献

欢迎您的帮助。请遵循我们的贡献指南

据了解，以任何形式，过去或将来提供的所有捐款都完全同意并接受MIT许可证。

运行规格

设置

bundle install
bundle exec appraisal install

列表定义的评估： 

bundle exec appraisal list

运行特定评估规格： 

bundle exec appraisal rails-6.1 rspec

所有评估的运行规格： 

bundle exec appraisal rspec

作者

  • piotr kuczynski
  • 弗雷德·吴
  • 雅克·克罗克（Jacques Crocker）
  • Christopher J. Bottaro从App config继承

贡献者

代码贡献者

该项目的存在得要归功于所有贡献的人，您非常欢迎您提供帮助。请遵循我们的贡献指南。

据了解，以任何形式，过去或将来提供的所有捐款都完全同意和接受MIT许可。

财务贡献者

成为支持者，并通过每月少量捐款来支持我们，以帮助我们继续我们的活动。谢谢你，如果你已经一个了！

赞助商

通过成为赞助商来支持这个项目。您的徽标将在此处显示您网站的链接。

执照

版权（C）Piotr Kuczynski。根据MIT许可发布。

下载源码

通过命令行克隆项目:

git clone https://github.com/rubyconfig/config.git

相关文章

nvim

2025-08-15

aesthetic wallpapers

2025-08-15

node convict

2025-08-16

tach

2025-08-16

推荐阅读

向上：银河游戏免安装正式版

2026-01-23

风暴驭使正式中文版

2026-01-23

冥河：贪婪之刃中文试玩版

2026-01-23

超级键盘侠免安装绿色中文版

2026-01-23