症状
本篇指南处理“Ruby NoMethodError — nil 上未定义的方法”。请从症状出发，按顺序执行诊断，在推进前确认每个假设；随后通过修复与验证步骤闭环。
可观察到的症状包括：
- NoMethodError: undefined method `name’ for nil:NilClass
- 记录存在时正常，不存在时失败
- 堆栈指向多级链式调用中的某处
诊断
先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。
步骤 1
ruby -e "begin; nil.name; rescue => e; puts e.backtrace.first(5); end"缺失方法上方的那一帧会显示哪个调用返回了 nil。
步骤 2
obj&.name.inspect&. 遇 nil 会短路；若结果为 nil，则说明该处接收者为 nil。
常见诱因（按出现频率排序）：
- 查找无匹配时返回 nil，调用方却继续链式调用
- 哈希查找对缺失键返回 nil 且无默认值
- 方法在早退分支返回 nil，调用方却假定为对象
根因
在 Ruby 中，对 nil 调用方法会抛 NoMethodError，因为 nil 是一个仅定义了少量方法的对象。缺陷在于 nil 流入了假定为活对象的代码。
修复
对确实可选的链式调用用安全导航（&.），为哈希查找提供默认值（带默认的 fetch），并让辅助函数在每条分支返回文档化的值以消除静默 nil。
注意：到处链式 &. 会掩盖设计缺陷；若值必需，更应在边界处保证非 nil。
user = User.find_by(email: '[email protected]') # => nil
# ❌ user.name raises NoMethodError for nil
# ✅ safe navigation
name = user&.name || 'anonymous'
# ✅ hash default
opts = {}
timeout = opts.fetch(:timeout, 5)
# ✅ fail fast at the boundary
user = User.find_by!(email: '[email protected]') # raises ActiveRecord::RecordNotFound验证
用缺失记录的输入重跑，确认得到受控结果而非异常；为 nil 路径补充测试。
修复后补充一条回归测试，复现原始症状，防止问题再次出现。
这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。