Madeira 实战：在 ARM 设备上运行 x86 程序的动态二进制翻译方案

1. 项目缘起：为什么我要折腾 Madeira

第一次看到“Madeira”这个词，很多人第一反应是葡萄牙那个产葡萄酒的岛屿。但在我们这行，尤其是最近这半年，Madeira 更多是指一个把 x86-64 应用搬到 ARM 设备上跑的开源兼容层项目。它的核心思路跟 FEX-Emu 很像，但 Madeira 更聚焦在移动端和嵌入式场景，尤其是 iOS 和 Android 设备上运行桌面级 x86 程序这件事。

我最早接触这个方向，是因为手头有一台闲置的 ARM 开发板，想跑一些只有 x86 版本的旧工具链。当时试过 Wine 加 Box86 的组合，也试过 FEX-Emu，但配置起来都挺折腾。后来在社区里看到有人提到 Madeira，说它在指令翻译层做了不少优化，尤其是对 SSE4.2 和 AVX 的模拟效率比早期方案好很多。抱着试试看的心态搭了一套环境，结果确实有些惊喜。

Madeira 本质上是一个用户态的 x86-64 到 ARM64 的动态二进制翻译器，配合 Wine 和 DXMT 这类图形翻译层，可以让原本为 Windows x86 编译的程序在 ARM 设备上跑起来。它解决的核心问题是：大量存量软件只有 x86 版本，而新硬件几乎全是 ARM 架构，重新编译不现实，虚拟机又太重。Madeira 走的是轻量级翻译路线，不需要完整模拟 CPU，而是把 x86 指令块动态翻译成 ARM64 指令，缓存起来重复使用。

这篇文章适合几类人看：一是手里有 ARM 设备想跑 x86 程序但不想装虚拟机的；二是对二进制翻译和兼容层技术感兴趣的；三是做跨平台工具链、需要评估不同方案可行性的。我会把整个搭建过程、参数调优、踩过的坑都摊开讲，尽量让不同基础的人都能照着做。

2. 核心架构拆解：Madeira 到底怎么把 x86 指令搬到 ARM 上

2.1 动态二进制翻译的基本原理

Madeira 的工作方式跟 QEMU 的用户态模拟有点像，但更轻。QEMU 是逐条指令解释执行，每条 x86 指令都要经过一次解码、翻译、执行的过程，开销很大。Madeira 用的是基本块翻译：它会把一段连续的 x86 指令识别成一个基本块，一次性翻译成对应的 ARM64 指令序列，然后缓存起来。下次再执行到这个块，直接跳转到缓存里跑，省掉重复翻译的开销。

这个思路跟 FEX-Emu 是一致的，但 Madeira 在几个地方做了取舍。第一，它不支持完整的 x86 内存模型，而是假设大部分程序不会依赖强内存序，用 ARM 的弱内存序加少量屏障指令来近似。第二，它对自修改代码的处理比较保守，遇到会改自己代码的程序会回退到解释执行。第三，它的寄存器分配策略更激进，把 x86 的 16 个通用寄存器尽量映射到 ARM 的 31 个通用寄存器上，减少内存访问。

这些取舍带来的结果是：对大多数常规应用，Madeira 的翻译效率比 QEMU 用户态高不少，实测在一些计算密集型任务上能到原生性能的 60% 到 80%。但遇到反调试、自解压、加壳的程序，可能会直接跑不起来或者性能骤降。

2.2 与 Wine、DXMT 的配合关系

Madeira 本身只负责 CPU 指令翻译，它不提供 Windows API。要让 Windows 程序跑起来，还需要 Wine 来提供 Win32/Win64 的 API 实现。Wine 在 ARM 上跑的时候，如果程序是 x86 的，Wine 的 PE 加载器会把 x86 的 PE 文件交给 Madeira 去翻译执行，而 Wine 自己的库如果是 ARM 原生编译的，就直接跑。

DXMT 则是另一层：它把 Direct3D 调用翻译成 Metal 调用。在 iOS 和 macOS 上，没有 Vulkan 和 OpenGL 的原生支持，DXMT 就成了跑 Windows 游戏和图形程序的关键。Madeira 负责 CPU 指令，Wine 负责系统 API，DXMT 负责图形 API，三者叠起来才是一个完整的运行环境。

这里有个常见的误解：很多人以为装了 Wine 就能跑 x86 程序。实际上在 ARM 设备上，Wine 本身如果是 ARM 原生编译的，它加载 x86 PE 文件时必须有 Madeira 或类似的翻译器介入，否则会直接报格式错误。所以顺序是：先有 Madeira 提供 x86 执行能力，再有 Wine 提供 Windows API，最后有 DXMT 提供图形能力。

2.3 为什么选择 Madeira 而不是其他方案

市面上能跑 x86 程序的方案不少，我列个表对比一下我实际用过的几个：

Madeira 的优势在于它对移动端做了专门优化，代码体积小，启动快，对 iOS 的沙盒限制也有一定适配。FEX-Emu 更偏向桌面，配置项多但文档相对分散。Box86 系列对 32 位支持好，但 64 位翻译效率不如 Madeira。所以如果你的目标是在 ARM 手机或平板上跑 x86 程序，Madeira 是目前比较平衡的选择。

3. 环境搭建实操：从零把 Madeira 跑起来

3.1 基础依赖安装

我是在一台 ARM64 的 Linux 开发板上做的，系统是 Ubuntu 22.04。如果你用其他发行版，包名可能略有不同，但思路一样。先装编译工具链和基础库：

sudo apt update sudo apt install -y build-essential cmake git python3 python3-pip sudo apt install -y libsdl2-dev libepoxy-dev libdrm-dev libgbm-dev sudo apt install -y libasound2-dev libpulse-dev libudev-dev

这些依赖里，SDL2 和 epoxy 是给图形层用的，asound 和 pulse 是音频，udev 是输入设备。如果你只跑命令行程序，后面几个可以省，但既然要跑 Wine，图形和音频基本跑不掉。

然后拉 Madeira 的源码：

git clone https://github.com/madeira-project/madeira.git cd madeira git submodule update --init --recursive

这里有个坑：Madeira 的仓库里有些子模块是放在第三方托管上的，国内网络拉取可能会超时。我的做法是先把主仓库克隆下来，然后手动改.gitmodules里的 URL，换成能访问的镜像地址。具体改哪个地址这里不展开，你根据自己网络情况找可用的源就行。

3.2 编译参数选择与计算

Madeira 的编译选项里，有几个关键参数直接影响翻译效率和兼容性：

mkdir build && cd build cmake .. \ -DCMAKE_BUILD_TYPE=Release \ -DMADEIRA_ENABLE_AVX=ON \ -DMADEIRA_ENABLE_SSE4=ON \ -DMADEIRA_CACHE_SIZE=256 \ -DMADEIRA_JIT_THREADS=4

CMAKE_BUILD_TYPE=Release是必须的，Debug 版本翻译出来的代码没优化，性能差好几倍。MADEIRA_ENABLE_AVX打开 AVX 指令支持，但要注意：如果你的 ARM 设备不支持 NEON 的某些扩展，开了反而会崩。我建议先关掉 AVX 编译一版，跑通了再开。

MADEIRA_CACHE_SIZE是翻译缓存的条目数，单位是千条。256 意味着缓存 25.6 万个基本块。这个值怎么定？我的经验是：跑小型工具 64 就够，跑大型游戏或 IDE 建议 512 以上。缓存太小会导致频繁淘汰，翻译开销反复出现；太大则占用内存，在移动设备上可能触发系统杀进程。我一般先用 256 试，看madeira --stats输出的缓存命中率，低于 85% 就往上加。

MADEIRA_JIT_THREADS是翻译线程数。ARM 设备通常有 4 到 8 个核心，设成物理核心数的一半比较稳。设太多会导致翻译线程和主线程抢 CPU，反而卡顿。

编译：

make -j$(nproc) sudo make install

编译过程大概 10 到 20 分钟，取决于设备性能。如果中途报错说找不到某个头文件，大概率是前面依赖没装全，回去补装对应的-dev包。

3.3 Wine 与 DXMT 的集成配置

Madeira 装好后，还需要 Wine。这里注意：不要用系统自带的 Wine，那个通常是给 ARM 原生程序用的，不带 x86 翻译支持。要从源码编译 Wine，并在编译时指定使用 Madeira 作为翻译后端。

git clone https://github.com/wine-mirror/wine.git cd wine ./configure --enable-win64 --with-madeira=/usr/local make -j$(nproc) sudo make install

--with-madeira这个参数是关键，它让 Wine 在加载 x86 PE 文件时调用 Madeira 的翻译接口。如果没有这个参数，Wine 会尝试自己处理 x86 指令，在 ARM 上直接失败。

DXMT 的配置相对独立，它主要是一个 D3D 到 Metal 的翻译层。在 Linux 上其实用不到 DXMT，因为 Linux 有 Vulkan 和 OpenGL。DXMT 主要是给 iOS 和 macOS 用的。如果你在 Linux 上跑，Wine 自带的 WineD3D 配合 Mesa 的软渲染或硬件驱动就够了。但如果你在 iOS 上折腾，DXMT 就是必需品，因为 iOS 没有 Vulkan，Metal 是唯一的图形 API。

4. 实际运行中的问题与排查记录

4.1 Wine 乱码问题的根源与解决

Wine 乱码是我遇到最多的反馈。表现是：程序能跑，但菜单、按钮、对话框里的文字全是方块或问号。这个问题在 ARM 上跑 x86 Wine 时特别常见，原因通常有三个：

第一，字体缺失。Wine 默认会去找系统字体，但 ARM Linux 发行版预装的字体往往不含 Windows 常用字体。解决办法是把 Windows 的字体文件（如 simsun.ttc、msyh.ttf）复制到 Wine 的字体目录：

cp /path/to/fonts/*.ttf ~/.wine/drive_c/windows/Fonts/

第二，区域设置不对。Wine 根据LANG环境变量决定用哪套字符集。如果LANG设成了C或POSIX，中文就会乱。改成zh_CN.UTF-8：

export LANG=zh_CN.UTF-8 export LC_ALL=zh_CN.UTF-8

第三，Madeira 的翻译缓存里如果混入了不同字符集的字符串常量，可能导致编码错乱。这种情况比较少见，但遇到的话清掉缓存重建就行：

rm -rf ~/.cache/madeira/*

我实测下来，90% 的乱码问题靠前两步就能解决。剩下 10% 是程序本身用了非 Unicode 编码且硬编码了代码页，这种只能改程序或打补丁。

4.2 性能调优：从卡顿到流畅的几步操作

Madeira 跑起来后，如果感觉卡，先别急着换方案，按下面几步排查：

第一步，看翻译缓存命中率。运行madeira --stats会输出缓存命中、翻译次数、执行次数等数据。命中率低于 80% 说明缓存太小或程序代码太分散，前者加MADEIRA_CACHE_SIZE，后者没办法，只能接受。

第二步，检查 JIT 线程数。用htop看翻译线程是不是跑满了。如果翻译线程一直 100% 而主线程在等，说明翻译跟不上执行，可以适当增加线程数。但注意，ARM 设备的核心数有限，设太多会互相抢资源。

第三步，关掉不必要的指令集模拟。如果你的程序不用 AVX，就在编译时关掉MADEIRA_ENABLE_AVX。AVX 指令的翻译比 SSE 复杂得多，关掉能省不少翻译时间。

第四步，用perf看热点。perf top能告诉你时间花在翻译上还是执行上。如果翻译占大头，说明缓存没起作用；如果执行占大头，说明翻译出来的代码质量不高，可能需要调优化等级。

我自己的经验是：一个典型的 x86 桌面程序，在 4 核 ARM 设备上，经过上述调优后，启动时间能从 30 秒降到 8 秒左右，交互延迟从明显卡顿降到基本可接受。但别指望达到原生速度，翻译层的开销是物理上绕不过去的。

4.3 常见问题速查表

这个表是我踩坑踩出来的，基本上覆盖了八成以上的常见问题。遇到表里没有的，先看日志，Madeira 和 Wine 的日志级别都可以调，MADEIRA_LOG=debug和WINEDEBUG=+all能输出非常详细的信息，虽然刷屏但定位问题很有效。

5. 跨平台扩展：iOS 与移动端的特殊考量

5.1 iOS 沙盒限制下的 Madeira 适配

在 iOS 上跑 Madeira 跟在 Linux 上完全是两码事。iOS 的沙盒不允许 JIT 编译，而 Madeira 的核心就是 JIT。所以直接跑是不行的，必须用 iOS 允许的方式：要么用解释模式（性能差很多），要么用提前编译（AOT），把 x86 代码在安装前就翻译成 ARM64。

AOT 模式下，Madeira 的工作流程变成：在桌面机器上先把目标程序的 x86 代码翻译成 ARM64，打包进 app，iOS 上直接执行翻译后的代码。这样绕开了 JIT 限制，但失去了动态翻译的灵活性，遇到自修改代码或动态生成的代码就没办法了。

我试过用这种方式跑一些老游戏，效果还行，但兼容性明显不如 Linux 上的 JIT 模式。而且 AOT 的翻译过程很慢，一个几百 MB 的程序可能要翻译几个小时。

5.2 移动端输入与显示的适配

iOS 和 Android 的输入方式跟桌面完全不同。Madeira 跑桌面程序时，鼠标和键盘事件需要映射到触摸屏上。我的做法是：单击映射为鼠标左键，长按映射为右键，双指滑动映射为滚轮。键盘的话，调出系统输入法，把按键事件转发给 Wine。

显示方面，桌面程序的分辨率往往比手机屏幕大，需要缩放。Wine 有WINEDLLOVERRIDES可以强制设置分辨率，但效果一般。更好的做法是在 DXMT 层做缩放，把渲染目标设成手机屏幕大小，然后让程序以为自己在跑一个低分辨率屏幕。

这些适配工作很琐碎，而且不同程序表现不一样。我的建议是：如果你只是想在手机上跑一两个特定程序，针对性地调；如果想做通用方案，工作量会非常大。

5.3 与 FEX-Emu 在移动端的对比

FEX-Emu 也有 ARM 版本，但在移动端上的成熟度不如 Madeira。FEX-Emu 的配置更复杂，对系统依赖更多，在 iOS 这种限制严格的环境里很难跑起来。Madeira 的代码更精简，依赖更少，更适合嵌入到 app 里。

不过 FEX-Emu 在桌面 Linux 上的兼容性和性能还是更好的，尤其是跑游戏。所以我的选择是：桌面用 FEX-Emu，移动端用 Madeira，各取所长。

6. 我个人在实际操作中的几点体会

折腾 Madeira 这段时间，最大的感受是：二进制翻译这件事，理论很美好，实操全是坑。每个程序都有自己的脾气，同样的配置在这个程序上跑得好，换个程序就崩。所以别指望一套配置通吃，准备好针对不同程序做微调。

另外，社区里关于 Wine 乱码、缓存调优的讨论很多，但真正有用的信息往往藏在 issue 的回复里，而不是文档里。遇到问题先搜 issue，比看文档快。

最后分享一个小技巧：如果你在 ARM 设备上跑 x86 程序只是为了用某个特定功能，先试试有没有 ARM 原生的替代品。很多时候，换个工具比折腾翻译层省事得多。Madeira 适合的是那些确实没有替代品、又必须在 ARM 上跑的场景。