Ruby项目迁移Zeitwerk自动加载遇类未初始化及深层目录加载失败

我来帮你梳理一下问题的可能原因和对应的解决方案，让Zeitwerk能正确加载你所有的Chess命名空间下的类和模块：

先排查核心匹配规则问题 #

Zeitwerk的自动加载完全依赖文件路径 ↔ 类/模块名的严格匹配，这是最容易出错的点：

• 确认lib/chess/display/chess_display.rb里的代码结构完全正确，比如：

  # 写法一：嵌套定义
  module Chess
    module Display
      class ChessDisplay
        # 你的代码逻辑
      end
    end
  end
  
  # 写法二：直接命名（同样有效）
  class Chess::Display::ChessDisplay
    # 你的代码逻辑
  end
  

• 检查大小写和下划线转驼峰是否完全对应：display目录对应Display模块，chess_display.rb对应ChessDisplay类，不能出现Chessdisplay这类拼写错误。

优化Zeitwerk配置，确保路径加载正确 #

你当前的手动loader配置有可以调整的地方，避免路径扫描问题：

#!/usr/bin/env ruby
require "zeitwerk"

loader = Zeitwerk::Loader.new
loader.tag = "chess" # 给loader加个标识，方便调试日志区分
# 用File.expand_path替代字符串拼接，避免跨系统路径或相对路径错误
loader.push_dir(File.expand_path("../lib", __FILE__))
# 去掉自定义GemInflector，默认规则已经适配下划线转驼峰的标准命名
# loader.inflector = Zeitwerk::GemInflector.new(__FILE__)

# 调试用：开启日志，查看Zeitwerk扫描的文件和对应类名
# loader.log!
# 调试用：强制加载所有文件，直接暴露加载错误
# loader.eager_load!

loader.setup

Chess.new.start

调试技巧：快速定位加载失败点 #

如果还是加载失败，用这两个调试手段快速排查：

1. 开启加载日志：添加loader.log!后运行脚本，终端会输出Zeitwerk扫描到的所有目录、文件，以及对应的类/模块映射，你可以直接看到chess/display/chess_display.rb是否被正确识别为Chess::Display::ChessDisplay。
2. 强制预加载：添加loader.eager_load!，Zeitwerk会在启动时加载所有文件，而不是惰性加载，这样如果有类名不匹配或文件语法错误，会直接抛出明确的错误信息，帮你定位问题文件。

可选：规范gem结构，简化配置 #

如果你的项目是按gem结构设计的，建议在根目录创建chess.gemspec文件，这样可以用更简洁的Loader.for_gem配置，避免手动路径配置的问题：

# chess.gemspec 示例内容
Gem::Specification.new do |spec|
  spec.name          = "chess"
  spec.version       = "0.1.0"
  spec.authors       = ["Your Name"]
  spec.email         = ["your@email.com"]

  spec.summary       = "A custom chess game implementation"
  spec.license       = "MIT"

  spec.files         = Dir["{bin,lib}/**/*", "LICENSE", "README.md"]
  spec.bindir        = "bin"
  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
  spec.require_paths = ["lib"]

  spec.add_dependency "zeitwerk"
end

之后bin/chess就可以简化为：

#!/usr/bin/env ruby
require "zeitwerk"

loader = Zeitwerk::Loader.for_gem
# loader.log! # 调试用
# loader.eager_load! # 调试用
loader.setup

Chess.new.start

内容的提问来源于stack exchange，提问作者Lorenzo Zabot