crystalruby配置手册：crystalruby.yaml与CrystalRuby.configure参数逐项详解

crystalruby配置手册：crystalruby.yaml与CrystalRuby.configure参数逐项详解

【免费下载链接】crystalrubyEmbed Crystal code directly in Ruby项目地址: https://gitcode.com/gh_mirrors/cr/crystalruby

crystalruby 是一款能在 Ruby 代码中直接内嵌 Crystal 代码、通过 FFI 桥接实现高性能调用的开源 gem。要让它发挥最大威力，正确配置是第一步。本手册将带你把 crystalruby 配置彻底搞懂：项目根目录下的 crystalruby.yaml 配置文件，以及 Ruby 代码中的 CrystalRuby.configure 编程式配置，所有参数逐项详解，从默认值到实际应用场景一网打尽。

一、认识 crystalruby 的两种配置方式

crystalruby 贴心地提供了两套等价的配置入口，你可以任选其一，也可以混合使用：

配置方式	载体	特点
crystalruby.yaml	项目根目录的 YAML 文件	声明式，适合团队统一、CI/CD 环境
CrystalRuby.configure	Ruby 代码块	编程式，可在运行时动态调整

两者的核心逻辑都收敛在同一个单例类CrystalRuby::Configuration中，源码位于 lib/crystalruby/config.rb，启动时会自动读取 crystalruby.yaml 作为初始值，之后用 configure 块覆盖即可。需要说明的是：每次执行 configure 之后，路径缓存会被重置，确保新配置立即生效。

二、快速生成配置文件的两种方法

在项目根目录执行crystalruby init（或bundle exec crystalruby init），crystalruby 会自动生成一份带合理默认值的 crystalruby.yaml，对应实现见 exe/crystalruby：

# crystalruby configuration file crystal_src_dir: "./crystalruby" crystal_codegen_dir: "generated" crystal_missing_ignore: false log_level: "info" single_thread_mode: false debug: true

三、crystalruby.yaml 参数逐项详解

以下是全部配置项的参数对照表，建议收藏备用：

参数名	默认值	作用
crystal_src_dir	./crystalruby	Crystal 源文件所在目录
crystal_codegen_dir	generated	自动生成的 Crystal 代码输出目录
crystal_project_root	当前工作目录	项目根目录，用于计算绝对路径
crystal_missing_ignore	false	本机缺少 Crystal 编译器时是否静默忽略
debug	false	是否以调试模式编译 Crystal 代码
verbose	false	是否输出详细编译日志
single_thread_mode	false	是否启用单线程模式（绕过 Reactor）
colorize_log_output	false	是否用彩色输出日志
log_level	info	日志级别，可用环境变量CRYSTALRUBY_LOG_LEVEL覆盖

1. crystal_src_dir：Crystal 源码目录

指定 Crystal 源代码存放的根目录，crystalruby 会把内嵌的 Crystal 代码按"库"（Library）拆分到该目录下，每个库包含src与lib子目录，详见 lib/crystalruby/library.rb。默认值./crystalruby意味着你的项目下会生成crystalruby/文件夹。

2. crystal_codegen_dir：生成代码目录

控制自动生成的.cr文件输出位置，默认是generated。这些文件是 crystalruby 根据你内嵌的 Crystal 方法自动翻译生成的，包含了函数、类型定义与 FFI 绑定等模板代码（对应 lib/crystalruby/templates 目录下的模板）。

3. crystal_project_root：项目根目录

默认取当前工作目录Pathname.pwd。它作为基准路径，配合crystal_src_dir计算出所有目录的绝对路径（如crystal_src_dir_abs）。

4. crystal_missing_ignore：缺少编译器时是否忽略

当系统检测不到crystal可执行文件时，默认会直接抛出异常终止程序。若设为true，则只记录错误日志而不中断，方便在未安装 Crystal 的环境中继续运行 Ruby 侧代码（逻辑见 lib/crystalruby.rb 的check_crystal_ruby!）。

5. debug：调试模式开关

这是最常用的性能开关。debug: true时以调试模式编译，编译快、便于排查；debug: false时编译命令会附加--release --no-debug参数，生成生产级优化产物，发布上线前务必关闭（见 lib/crystalruby/compilation.rb）。

6. verbose：详细日志输出

开启后，编译命令会附带--verbose --progress，并打印 shards 安装等过程的完整输出，是排查编译问题的一大利器。

7. single_thread_mode：单线程模式

默认false时，crystalruby 通过 Reactor 把多线程调用多路复用到一个线程，存在约 10 微秒/次的开销。如果你的程序本身是单线程的，开启此模式可绕过 Reactor 大幅提升高频小函数的调用性能（源码见 lib/crystalruby/reactor.rb）。

8. colorize_log_output：彩色日志输出

开启后日志会带[crystalruby] [线程ID]前缀并着色，多线程调试时区分度更高。

9. log_level：日志级别

支持debug、info、warn、error四级，也可以直接设置环境变量CRYSTALRUBY_LOG_LEVEL，两者都作用于同一个 Logger 实例。

四、CrystalRuby.configure 编程式配置详解

在 Ruby 中，用代码块配置的效果与 yaml 完全一致，属性名一一对应：

CrystalRuby.configure do |config| config.crystal_src_dir = "./crystalruby" config.crystal_codegen_dir = "generated" config.crystal_missing_ignore = false config.debug = true config.verbose = false config.colorize_log_output = false config.log_level = :info config.single_thread_mode = false end

一个真实案例：crystalruby 自己的测试代码就是这样配置的，见 test/test_helper.rb，其中config.log_level = :warn降低了测试日志噪音，config.single_thread_mode则由环境变量CRYSTAL_RUBY_SINGLE_THREAD_MODE动态控制。

五、各参数的应用场景速查

场景	推荐配置
开发调试阶段	debug: true+verbose: true+log_level: debug
生产环境发布	debug: false（release 编译）+ 提前CrystalRuby.compile!预编译
高性能单线程程序	single_thread_mode: true
未安装 Crystal 的环境	crystal_missing_ignore: true
CI 多任务日志区分	colorize_log_output: true

六、配置加载顺序与优先级

crystalruby 的配置解析遵循"后写者优先"的原则，加载顺序为：

1. 项目根目录读取crystalruby.yaml（作为初始默认值）；
2. 程序运行到CrystalRuby.configure块时覆盖同名参数；
3. 环境变量CRYSTALRUBY_LOG_LEVEL可单独覆盖日志级别。

也就是说，yaml 适合放"团队共识"，configure 适合放"当前进程特有"的调整。

七、配置相关常见问题

Q1：提示 "Crystal executable not found" 怎么办？说明本机缺少 Crystal 编译器。安装 Crystal 后重试；若只是临时运行 Ruby 代码，可将crystal_missing_ignore设为true。

Q2：编译产物异常、代码不生效？执行bundle exec crystalruby clean清理src/generated与lib缓存目录，重新编译即可，对应实现见 exe/crystalruby。

Q3：改了 yaml 没生效？确认 crystalruby.yaml 位于项目根目录，且 configure 块中没有再次覆盖同名参数。

结语

至此，crystalruby.yaml 与 CrystalRuby.configure 的全部参数你已了然于胸：9 个配置项、两套等价入口、一条加载优先级规则。正确配置是让 Ruby 与 Crystal 高效协作的地基，按照本手册逐项核对，你就能让 crystalruby 在开发与生产环境中都稳定高效地运转起来。

【免费下载链接】crystalrubyEmbed Crystal code directly in Ruby项目地址: https://gitcode.com/gh_mirrors/cr/crystalruby