企业官网建设流程全解析

• 编程语言
• 语言运行时
• 编译器
• 解释器
• 嵌入式

mruby 的哲学是"轻量级地实现 Ruby ISO 标准"，而 Ruby 是一门表达力强、实现细节复杂的语言，这两个目标天然部分冲突。为此，mruby 官方在 doc/limitations.md 中系统性地定义了与 CRuby 的兼容性边界，本文以该文档为主体，结合仓库源码与构建配置逐条展开解读，帮助你在把 Ruby 代码移植到 mruby、或为嵌入式设备裁剪构建时，快速定位"报错不是 bug 而是设计"的场景，并给出对应的解法。

注意：本文整理的是一份当前已知限制的合集，官方明确声明它并非完整清单（见 doc/limitations.md），实际移植中仍可能遇到未收录的差异。欢迎在实践中补充发现。

一、定位：轻量级与兼容性的天然矛盾

mruby 的核心定位是"轻量级（lightweight）"。它追求的是在嵌入式设备、游戏机、内存受限环境里跑起 Ruby 语法，因此许多 CRuby 为了表达力而付出的内存与实现复杂度，在 mruby 里被刻意省略。这些省略多数是设计决策而非缺陷，理解这一点是阅读本文的前提：你在 mruby 中遇到的NoMethodError或NameError，往往不是"mruby 不支持这个功能"，而是"提供该功能的 mrbgem 没有被链接进构建"。

二、功能由 mrbgems 提供：先查 gembox 再谈兼容

CRuby 把大量功能编译进核心，而 mruby 将许多 Ruby 特性做成独立的 mrbgem，哪些功能可用完全取决于构建时链接了哪些 gem。

default.gembox与stdlib.gembox覆盖了最常见场景，但一个最小化构建（例如 build_config/minimal.rb 这类配置）可以省略掉我们非常熟悉的功能：

• Kernel#binding—— 由 mruby-binding 提供；
• Kernel#catch/throw—— 由 mruby-catch 提供；
• Enumerable扩展、Comparable、IO、正则表达式等更多功能。

以仓库实际的 gembox 配置佐证： mrbgems/stdlib.gembox 明确列出mruby-compar-ext（Comparable 扩展）、mruby-enum-ext（Enumerable 扩展）、mruby-regexp（正则）、mruby-io（IO，位于 mrbgems/stdlib-io.gembox）等；而 mrbgems/default.gembox 则在其上叠加math、metaprog等 gembox 并生成mrbc、mirb、mruby、mruby-strip等命令行工具。

移植建议：当 Ruby 代码在 mruby 下报NoMethodError/NameError时，优先怀疑"对应 gem 未链接"，而不是"mruby 不支持"。在构建配置里加入相关 gem（如conf.gem :core => "mruby-catch"）通常即可解决。

三、Fiber 不能跨越 C 函数边界

mruby 的Fiber实现方式与 Lua 的协程（co-routine）类似，由此产生一个直接后果：无法在 C 函数内部切换上下文。唯一例外是返回时的mrb_fiber_yield。

也就是说，在 C 扩展中你不能在任意 C 函数里挂起/恢复 Fiber，只能在 Ruby 层的 Fiber 调用链中进行 yield/resume。从源码看，Fiber 的切换依赖于虚拟机调用栈与mrb_context（见 src/vm.c 关于 fiber 保存根槽的描述、src/vm.c 的CINFO_RESUMED等状态标记），C 函数帧不在可切换的上下文管理范围内，因此跨 C 边界切换在 mruby 中不可行。编写 C 扩展时请勿依赖在 C 回调中主动 yield。

四、Array不支持实例变量

为降低内存消耗，mruby 的Array不保存实例变量。这意味着继承Array的子类无法通过@field之类的实例变量保存状态：

class Liste < Array def initialize(str = nil) @field = str end end p Liste.new "foobar"

• CRuby：输出[]（实例变量正常保存）。
• mruby：抛出ArgumentError。

这是"为省内存而砍功能"的典型例子——数组对象在 mruby 中不携带 iv 表，为每个 Array 保留实例变量槽位会显著增加内存占用。移植时请改用其他方式为数组子类保存状态（如外部哈希、或改用Struct包装）。

五、defined?的行为差异

defined?在 mruby 中与 CRuby 有三点差异：

1. 返回结果不是同一个对象：defined?(self).equal?(defined?(self))在 CRuby 下为true，mruby 下为false；
2. 超过 32 层的常量路径返回nil；
3. mruby 不存在的名称（如$PROGRAM_NAME、__dir__）也返回nil——因为它们是"不存在"而非"以不同方式未定义"。

验证代码：

defined?(self).equal?(defined?(self)) defined?(A::B::C::D::E::F::G::H::I::J::K::L::M::N::O::P::Q::R::S::T::U::V::W::X::Y::Z::A::B::C::D::E::F::G)

六、全局变量不支持alias

CRuby 允许给全局变量取别名，但这不是 ISO 标准要求的行为，mruby 不支持：

alias $a $__a__

• CRuby：返回nil（别名建立成功）。
• mruby：语法错误（Syntax error）。

移植时遇到alias $x $y请改写为直接赋值或通过$y引用。

七、条件表达式中nil?的重定义被忽略

在条件表达式里，mruby 忽略对nil?的重定义，直接用对象真值性判断：

a = "a" def a.nil? true end puts(a.nil? ? "truthy" : "falsy")

• CRuby：输出truthy（调用了单例方法a.nil?）。
• mruby：输出falsy（条件判断不走nil?方法分发，直接按真值性判定）。

这意味着不能依赖重定义nil?来改变if obj/obj ? ...这类条件表达式的走向。

八、模块加载不使用双分派（No Double Dispatch）

为简化实现，mruby 在模块加载（include/prepend/extend）时不采用双分派。CRuby 中这些方法内部会调用对应的实际加载方法（append_features/prepend_features/extend_object），从而允许用户覆写它们做钩子；mruby 直接执行加载逻辑，不回调这些方法。

module M def self.append_features(mod) p :append end end class C include M end

• CRuby：打印:append。
• mruby：什么都不打印（include内部不调用append_features）。

从源码可以直接印证： src/class.c 中mrb_mod_prepend的实现直接调用mrb_prepend_module()完成加载，只在模块定义了prepended回调（mrb_func_basic_p判断）时才调用之，而不经过prepend_features的方法分发。

官方文档给出的取舍理由是：这些方法很少被覆写，保留双分派会消耗更多内存、且让模块加载略微变慢。作为面向小型设备的 Ruby 实现，mruby 选择更简单的方案。

九、小哈希表不调用#hash方法

出于性能考虑，当哈希表规模较小时，mruby 不会对键调用#hash方法。也就是说，键对象上自定义的#hash方法在小哈希中可能根本不会被执行。

这直接影响依赖自定义#hash/#eql?的对象作为 Hash 键的代码：在小哈希（元素数量低于某个内部阈值）中，mruby 可能直接按对象身份或内置哈希逻辑处理，导致"键相等性"表现与 CRuby 不一致。移植涉及自定义#hash键的代码时需特别测试。

十、模式匹配（Pattern Matching）的一处差异

mruby 的case/in及其接受的模式，回答（匹配结果）与 CRuby 基本一致，唯一例外是：当#deconstruct返回的不是 Array 时，mruby 选择跳过该子句继续匹配，而 CRuby 会抛出TypeError。

class Odd def deconstruct = 42 end case Odd.new in [x] then x else :no end

• CRuby：抛出TypeError。
• mruby：返回:no——即该值落到下一个子句。

另外，#deconstruct_keys被限定为必须返回 Hash，且对象若两个钩子都没有实现，则直接落到下一个子句（不报错）——这两点与 CRuby 行为一致。

十一、Refinements 是可选功能（Opt-in）

模块细化（refine、using）仅在定义了MRB_USE_REFINEMENTS的构建中可用，其生效范围与语义见 doc/guides/mrbconf.md。

从仓库实现看：

• include/mrbconf.h 中该宏默认未开启（配置段中以注释形式存在）；
• include/mruby/class.h 中MRB_FL_CLASS_IS_REFINEMENT/MRB_FL_CLASS_IS_REFINED两个标志位均包裹在#ifdef MRB_USE_REFINEMENTS内；
• src/refinement.c 整个文件即"Refinement 类与using（MRB_USE_REFINEMENTS）"的实现，只有开启宏才会编译。

mrbconf.md 进一步说明：开启后支持Module#refine、Module#refinements、main.using、Module#using、Module.used_modules、Module.used_refinements，细化作用域按词法生效，super可到达被细化的类，且细化优先于类的前置模块（prepend）链；同时指出"被保护运算符（Integer#+、String#[]、==等）的细化"存在范围限制。因此，若你的构建未开启该宏，使用refine/using的代码将直接报错——这是构建配置问题，不是运行时 bug。

十二、没有Encoding类

mruby 没有Encoding类，字符串默认按字节序列处理。相关能力通过编译标志控制：

• MRB_UTF8_STRING（见 include/mrbconf.h）：开启后字符串操作具备 UTF-8 感知能力，且大小写转换遵循 Unicode 而非 ASCII；
• MRB_USE_ASCII_CTYPE：在保留 UTF-8 索引能力的同时，把大小写转换等收窄回 ASCII 行为。

在 Unicode 转换行为上：

• 一个完整的 Unicode 转换会对"拼不出任何字符的字节"抛出ArgumentError；
• 收窄到 ASCII 的转换则"读不到字符"，把这些字节原样交还（不做处理）。

从源码看，include/mruby/internal.h 中MRB_UTF8_STRING与MRB_USE_ASCII_CTYPE的组合直接决定字符分类（ctype）表的分支；include/mruby/string.h 中字符串长度、字符索引等 API 也随该宏改变语义（例如mrb_str_substr在MRB_UTF8_STRING下按字符计数）。移植涉及编码的代码时，请先确认目标构建的字符串宏组合。

十三、整数精度随 Boxing 模式变化

mruby 的整数取值范围取决于值装箱（value boxing）配置，官方文档给出如下对照：

依赖于 64 位整数精度的代码在不同配置下行为可能不同。从 include/mrbconf.h 可以看到实际的默认推导逻辑：未显式指定时默认MRB_WORD_BOXING；整数宽度方面，MRB_INT32与MRB_INT64互斥，64 位架构且非 NaN boxing 时默认MRB_INT64，否则默认MRB_INT32；MRB_NAN_BOXING下按 NaN 盒布局，整数范围收紧到 32 位有符号区间。

解法：当需要任意精度整数时，在构建中加入 mruby-bigint gem，它提供任意精度整数支持。注意 NaN boxing 场景（doc/guides/boxing.md 有专门介绍）的精度上限。

十四、ObjectSpace默认不可用

ObjectSpace只能通过 mruby-objectspace gem 获得（它被包含在stdlibgembox 中，见 mrbgems/stdlib.gembox）。即便启用该 gem，ObjectSpace.each_object的功能相比 CRuby 也有限（例如遍历范围、回调语义均有简化）。依赖ObjectSpace做元编程或调试的代码，移植前需确认 gem 已链接，并降低对遍历能力的预期。

十五、没有隐式类型转换（to_int、to_str、to_ary等）

这是影响面最广的差异之一。mruby 不通过to_int、to_str、to_ary、to_hash这类方法做隐式类型转换。CRuby 允许用户类通过它们鸭子类型伪装成内建类型——例如Array#[]会对参数调用to_int，String#+会调用to_str，多重赋值会对右侧调用to_ary；mruby 的内建操作要求实参是真正的内建类型，不会咨询这些转换方法。

class MyInt; def to_int; 42; end; end class MyStr; def to_str; "x"; end; end class MyAry; def to_ary; [1,2,3]; end; end

细节边界：

• 身份版本仍存在：to_int、to_str、to_sym、to_hash的身份版本（identity versions）仍定义在对应内建类型上，因此respond_to?(:to_str)这类检查对内建实例仍然成立；
• 刻意缺失：Float#to_int与Array#to_ary有意不定义；
• 显式转换不受影响：to_i、to_s、to_a等显式转换方法与 CRuby 一致工作，字符串插值和展开运算符（*obj）仍会调用它们。

这是刻意的权衡：隐式转换迫使每个强转点都走一次方法分发，而且可能静默掩盖类型不匹配的 bug。mruby 选择显式、严格的类型边界。移植鸭子类型风格的代码时，请改为显式调用to_int/to_str等方法。

十六、Proc#dup/Proc#clone始终是孤儿块

传给方法的块的dup或clone，在 mruby 中从创建那一刻起就被当作孤儿块（orphan block）——只要块内含break或return，调用它就会抛出LocalJumpError。CRuby 更精细：副本继承原块的孤儿状态，只有当原块的 yield 方法返回后，副本才变成孤儿。

def m(&b) b.dup end x = m { break 1 } x.call

• CRuby：LocalJumpError—— 仅在m返回后抛出；如果在m内部调用该 dup，它仍是活块（live block）。
• mruby：LocalJumpError—— 总是抛出，dup 从创建那一刻起就是孤儿。

官方文档给出的动机非常明确：mruby 更严格的规则让RProc无需保存指向原块的反向指针（back-pointer），从而也缩小了 GC 标记集（mark set）。这也是"用严格语义换内存"的又一实例。

十七、Class#initialize可被重复调用

CRuby 在initialize被调用到已经设置完成的类上时抛出TypeError: already initialized class；mruby 的Class#initialize没有这道防护——通过__send__、send或UnboundMethod#bind_call对已存在的类再次调用会静默成功：

Klass = Class.new Klass.__send__(:initialize) {}

• CRuby：TypeError: already initialized class。
• mruby：在Klass的上下文（receiver）中执行传入的块，不抛错；即使传入超类参数，类的层级也不会被改写。

关键语义：重复调用时超类参数被忽略，因此该路径不可能改写类层级；只有块（若有）以该类为 receiver 被求值。Module#initialize在两个实现中都可重入，所以这一差异是Class特有的。

源码层面的理由：要加 CRuby 那道检查，需要给每个RClass额外占一个标志位（flag bit）。mruby 认为这条路径不会产生破坏性副作用，于是省下了这个位——在 include/mruby/class.h 的 RClass 标志位布局中，可以看到9-15: unused这类预留位正是"能不花就不花"的设计哲学的体现。

十八、总结：把"限制"当作构建与移植的输入

综合以上各条，可以提炼出 mruby 兼容性限制的三大主线：

1. 内存优先：Array不持 iv、Proc#dup立即孤儿化、RClass不设"已初始化"标志位、小哈希不调#hash——处处体现"少一个字段、少一个标志位、少一次分发"；
2. 实现简化：Fiber 不跨 C 边界、模块加载无双分派、无隐式类型转换——把 VM 与内建方法的实现路径缩短；
3. 构建可裁剪：Refinements、Encoding/UTF-8、ObjectSpace、模式匹配细节、任意精度整数等都由编译宏或 mrbgem 决定——功能边界由 include/mrbconf.h、gembox 与 build config 共同刻画。

对开发者而言，最有价值的实践是：遇到行为差异先查 doc/limitations.md 与 doc/guides/mrbconf.md，再检查构建配置（gembox 与编译宏）——多数"兼容性问题"在 mruby 里是"功能未链接"或"配置未开启"，而非实现缺陷。这份清单会随版本演进持续更新（各版本变更可参考 NEWS.md 与 doc/mruby3.0.md 至 doc/mruby4.0.md），移植前对照当前版本的文档与源码（核心实现见 src/array.c、src/class.c、src/vm.c、src/refinement.c）是最可靠的做法。

• 编程语言
• 语言运行时
• 编译器
• 解释器
• 嵌入式