crystalruby配置手册crystalruby.yaml与CrystalRuby.configure参数逐项详解【免费下载链接】crystalrubyEmbed Crystal code directly in Ruby项目地址: https://gitcode.com/gh_mirrors/cr/crystalrubycrystalruby 是一款能在 Ruby 代码中直接内嵌 Crystal 代码、通过 FFI 桥接实现高性能调用的开源 gem。要让它发挥最大威力正确配置是第一步。本手册将带你把 crystalruby 配置彻底搞懂项目根目录下的 crystalruby.yaml 配置文件以及 Ruby 代码中的 CrystalRuby.configure 编程式配置所有参数逐项详解从默认值到实际应用场景一网打尽。一、认识 crystalruby 的两种配置方式crystalruby 贴心地提供了两套等价的配置入口你可以任选其一也可以混合使用配置方式载体特点crystalruby.yaml项目根目录的 YAML 文件声明式适合团队统一、CI/CD 环境CrystalRuby.configureRuby 代码块编程式可在运行时动态调整两者的核心逻辑都收敛在同一个单例类CrystalRuby::Configuration中源码位于 lib/crystalruby/config.rb启动时会自动读取 crystalruby.yaml 作为初始值之后用 configure 块覆盖即可。需要说明的是每次执行 configure 之后路径缓存会被重置确保新配置立即生效。二、快速生成配置文件的两种方法在项目根目录执行crystalruby init或bundle exec crystalruby initcrystalruby 会自动生成一份带合理默认值的 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./crystalrubyCrystal 源文件所在目录crystal_codegen_dirgenerated自动生成的 Crystal 代码输出目录crystal_project_root当前工作目录项目根目录用于计算绝对路径crystal_missing_ignorefalse本机缺少 Crystal 编译器时是否静默忽略debugfalse是否以调试模式编译 Crystal 代码verbosefalse是否输出详细编译日志single_thread_modefalse是否启用单线程模式绕过 Reactorcolorize_log_outputfalse是否用彩色输出日志log_levelinfo日志级别可用环境变量CRYSTALRUBY_LOG_LEVEL覆盖1. crystal_src_dirCrystal 源码目录指定 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: trueverbose: truelog_level: debug生产环境发布debug: falserelease 编译 提前CrystalRuby.compile!预编译高性能单线程程序single_thread_mode: true未安装 Crystal 的环境crystal_missing_ignore: trueCI 多任务日志区分colorize_log_output: true六、配置加载顺序与优先级crystalruby 的配置解析遵循后写者优先的原则加载顺序为项目根目录读取crystalruby.yaml作为初始默认值程序运行到CrystalRuby.configure块时覆盖同名参数环境变量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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考