Ruby 常量查找与自动加载机制（Zeitwerk）是怎么回事
Ruby 常量解析受到词法嵌套和祖先链影响，Zeitwerk 使用原生 autoload 管理自动加载。本文讲清常量解析规则、常见陷阱，以及 Rails Zeitwerk 自动加载的工作原理。
Ruby 的未限定常量查找先考虑词法嵌套，再按定义上下文查祖先链；限定名称的规则有所不同，查找失败才调用 const_missing——Zeitwerk 使用 Ruby 原生 autoload 机制实现"用到才加载"的自动加载机制。理解这个顺序，就能解释绝大多数"明明定义了却报 NameError"的问题。
常量不只是"不变的值"
Ruby 中首字母大写的标识符都是常量：类名、模块名、MAX_SIZE = 100 这类值，本质上都存放在常量表里。常量可以重新赋值（只会收到警告而非报错），所以"常量"更接近"约定不改的全局名"。
真正重要的是常量附着在类/模块上形成的命名空间，以及那套固定的查找规则。
常量查找的三步顺序
下面是理解未限定常量名的常用顺序；限定访问 A::B 和紧凑定义的上下文需另行区分：
- 词法作用域（Lexical scope）：从代码书写位置的嵌套结构由内向外找；
- 祖先链（Ancestry）：当前类的父类、混入的模块里找；
- 顶层常量：是否能访问 Object 上的顶层常量还取决于当前类／模块上下文，不能用于推断所有限定查找。
都找不到时，调用 Module#const_missing。这个顺序决定了下面这段代码的行为：
class User; end
module Admin
class User; end
def self.lookup
User # 词法作用域优先，解析为 Admin::User
end
end
想强制访问顶层常量，需要写成 ::User。
经典陷阱：词法作用域 ≠ 运行时嵌套
class Admin::User 这种紧凑定义方式会改变词法作用域——块内看不到 Admin 命名空间里的其他常量，因为 Module.nesting 只有 [Admin::User]。这是新人最常踩的坑：改成 module Admin; class User; ... end; end 的完整嵌套写法就能避免。
const_missing 与 Zeitwerk 的区别
const_missing 是常量查找失败时的最后一道钩子：
module Api
def self.const_missing(name)
puts "常量 #{name} 被请求但不存在"
super
end
end
Api::Client # 输出提示后抛 NameError
Zeitwerk 会扫描受管理的目录，并通过 Ruby 的 autoload 为常量注册延迟加载。经典 Rails 自动加载器曾依赖 const_missing，不能把那套实现套到 Zeitwerk 上。生产环境可以启用 eager loading，开发环境的重新加载则由框架生命周期管理。
对应的约定是：文件名必须和常量名严格对应——在常规 root 与 inflector 配置下，Admin::User 对应 admin/user.rb；自定义命名空间及 inflector 会改变映射。命名不一致时报的 Zeitwerk::NameError 可能表示文件加载后未定义预期常量，应核对文件内容与命名映射。
调试常量问题的实用手段
Module.nesting：查看当前词法嵌套；User.ancestors：查看祖先链；Zeitwerk::Loader.eager_load_all：生产模式预加载全部代码，提前暴露命名错误；- 在
config/application.rb里开启Rails.autoloaders.log!观察加载顺序。
常见问题（FAQ）
Q：为什么开发环境正常、生产环境报 NameError？
生产环境默认 eager load，加载顺序可能与开发环境不同，暴露了隐式依赖。本地用 RAILS_ENV=production bin/rails runner 'Rails.application.eager_load!' 或 CI 里跑 rails zeitwerk:check 可以提前发现。
Q：autoload 和 require 有什么区别？
require 立即加载文件；autoload 注册延迟加载（常量首次被引用时才 require）。Zeitwerk 基于原生 autoload 管理文件与常量映射，并提供线程安全加载；代码重载仍需按框架约定协调。
Q：常量真的不能改吗？
技术上可以重新赋值（只有警告），但不要这么做。需要可变配置时用普通变量、类属性或配置对象。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
