15 个常见 Ruby 错误及解决方法（附生产环境处理方案）
NoMethodError、NameError、SystemStackError……本文盘点 Ruby 开发中最常见的 15 种错误，逐一分析成因与修复方法，并给出生产环境集中管理异常的监控方案。
Ruby 报错都有固定套路：NoMethodError 是调了不存在的方法（多半是 nil），NameError 是名字没定义（拼写或加载顺序），TypeError/ArgumentError 是传参问题，SystemStackError 是无限递归。掌握每个错误的典型诱因，看一眼报错信息就能定位方向。
1. SyntaxError
解析期错误：少 end、括号不配对、字符串没闭合。编辑器语法高亮 + ruby -c file.rb 秒查；多行方法链少逗号是高频变体。
2. NoMethodError
出现率冠军。undefined method 'name' for nil 意味着你在 nil 上调方法——上游查询没查到数据。修复：安全导航 user&.name、提前 return 判空、或 find_by! 让查不到时明确报错。另一种变体是私有方法被外部调用（private method 'x' called）。
3. NameError
常量/变量名未定义：拼写错误、类名大小写不符、文件没被加载。Rails 里报 uninitialized constant 先查文件名与常量名是否符合 Zeitwerk 约定（Admin::User ↔ admin/user.rb）。
4. TypeError
类型不符：nil + 1、把字符串当数组用。防御：边界处用强转（to_i、to_s）或 dry-types 显式约束，核心逻辑内避免隐式类型假设。
5. ArgumentError
参数个数或值不对：wrong number of arguments (given 3, expected 2)。关键字参数时代的高频错：方法定义 def f(a:) 而调用传了位置参数。善用 RuboCop 和编辑器参数提示。
6. LoadError / 7. Errno::ENOENT
cannot load such file：require 路径错误或 gem 没装进当前环境（检查 bundle exec 与 Gemfile 分组）。No such file or directory：文件路径错——用绝对路径（Rails.root.join）替代相对路径，工作目录变化是相对路径失效的主因。
8. ZeroDivisionError / 9. IndexError / 10. KeyError
除以零：除数来自计算或外部数据时先判零。IndexError：数组越界（少见，Ruby 越界返回 nil 而非报错——这个设计本身坑了不少人）。KeyError：Hash#fetch 取不存在的键，恰是它比 hash[:key] 更可靠的地方——缺失立刻暴露而不是传 nil 到下游。
11. RegexpError / 12. SystemStackError
正则语法错：用户输入拼进正则前必须 Regexp.escape。栈溢出：常见原因是无限递归——递归方法检查终止条件，或两个方法互相调用（to_s 与 inspect 互调是经典变体）。
13. Encoding::CompatibilityError
字符串编码冲突：拼接 UTF-8 与 GBK/ASCII-8BIT 数据时爆炸。修复：force_encoding('UTF-8')、读取时指定 encoding: 参数，二进制数据一律用 BINARY 模式。
14. IOError / 15. ThreadError
IOError：操作已关闭的流（ensure 里 close 后又用了一次）。ThreadError：线程同步问题——锁重入、从空队列 pop（非阻塞模式）、信号 trap 里调用了带锁方法。多线程代码优先用 Queue、Concurrent::Map 等同步原语，别自己撸锁。
从单个 Ruby 错误追查影响范围
修复一个 NameError 或 NoMethodError 之前，先判断它是否只出现在某个版本、接口或 Worker。应用输出结构化异常日志后，通过 DataKit 采集并配置解析，在观测云里按异常类型与 service、env、version 归类。对持续错误设置监控器，并用兼容的 Ruby APM 插桩补充调用路径；告警阈值和通知对象需要按业务影响配置。
接入文档：日志采集 · Ruby APM 接入 · 监控器与告警策略。
常见问题（FAQ）
Q：报错信息很长，先看哪里？
第一行（异常类 + 消息）定方向，堆栈最上面几行定位置， Rails 环境重点看 app/ 目录下的帧——gem 内部的帧通常是受害者而非肇事者。
Q：有些错误只在生产出现，本地复现不了怎么办？
九成是数据差异：生产数据的边界值（空数组、超长文本、特殊字符）触发本地遇不到的路径。拿到生产报错的完整上下文（参数、用户、数据 id）后在本地用相同数据复现，或临时加日志打点观察。
Q：应该用 rescue 兜住所有错误防止 500 吗？
不要。无差别兜底让错误隐形——用户看到正常页面但数据已坏。正确姿势：预期内的错误分类 rescue，预期外的让它 500 并被监控捕获，发现一处修一处，错误率才会真正下降。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
