1. 从“Madeira”这个名字说起它到底想解决什么问题第一次看到“Madeira”这个项目名很多人会以为是某个旅游地或者葡萄酒品牌。但把 FEX-Emu、Wine、DXMT、iOS、x86-64 这几个关键词摆在一起方向就清楚了这是一个围绕x86-64 应用在非 x86 平台上运行的兼容层整合项目。说得再直白一点它想做的事情是让原本为 Windows/x86-64 编译的程序能在 ARM 设备、尤其是移动端和国产化桌面环境里跑起来而且尽量少折腾。我自己接触这类方案是从 Wine 开始的。早期在 Linux 上跑 Windows 软件Wine 是绕不开的一环后来苹果 M 系列芯片出来FEX-Emu 这类 x86-64 指令翻译层进入视野再往后DXMT 把 Direct3D 转到 Metal补齐了图形这一块。Madeira 的价值就在于它没有重新造轮子而是把这几块拼成了一条相对完整的链路指令翻译 Windows API 兼容 图形 API 转换 移动端/桌面端适配。适合谁看如果你在做国产化系统适配、在 ARM 服务器上跑遗留 Windows 工具、或者单纯想在移动设备上体验一些老游戏和老软件这篇内容都能给你一条可参考的路径。它不是那种“一键安装包”式的教程而是把每个环节为什么这么选、坑在哪里讲清楚让你遇到问题时知道往哪个方向查。需要先说明一点下面涉及的很多参数和步骤是基于这类兼容层项目的常见实践补全的具体版本行为可能随更新变化实操时以你手头版本的文档为准。2. 整体架构拆解四层结构各管什么2.1 为什么是“翻译 兼容 转换”三层叠加要理解 Madeira 的设计先得把 x86-64 程序在 ARM 上运行这件事拆开。一个 Windows 程序从点击图标到画出窗口大致经过CPU 执行指令、调用 Windows 系统 API、通过图形 API 渲染画面。这三件事在 x86-64 Windows 环境下是原生支持的换到 ARM Linux/macOS/iOS 上每一层都要补。FEX-Emu 负责第一层把 x86-64 指令动态翻译成 ARM64 指令。Wine 负责第二层把 Windows API 调用翻译成 POSIX 调用。DXMT 负责第三层把 Direct3D 调用翻译成 Metal 调用。最外面那层是平台适配决定这套东西跑在桌面 Linux、macOS 还是 iOS 上。注意这三层不是简单串联而是有交叉。比如 Wine 内部也会调用图形接口DXMT 需要和 Wine 的窗口系统配合FEX-Emu 又要处理 Wine 产生的系统调用。层与层之间的边界处理往往是问题最多的地方。2.2 FEX-Emux86-64 到 ARM64 的翻译层FEX-Emu 的核心是动态二进制翻译。它不提前把整个程序翻译好而是在程序运行时遇到一段 x86-64 指令就翻译一段翻译结果缓存起来下次遇到同样代码直接复用。这样做的好处是启动快、内存占用可控坏处是首次执行有翻译开销对性能敏感的场景会有波动。它支持两种模式一种是JIT 模式边跑边翻译适合大多数场景另一种是AOT 模式提前把常用库翻译好减少运行时开销。实际用下来JIT 模式兼容性更好AOT 模式在特定负载下更稳。选择哪种取决于你的程序是交互式还是批处理式。FEX-Emu 还处理了 x86-64 的内存模型和原子操作。x86 是强内存模型ARM 是弱内存模型直接翻译会导致多线程程序出现难以复现的 bug。FEX-Emu 在翻译时插入内存屏障保证语义一致。这部分开销不小但省不掉。2.3 WineWindows API 的兼容实现Wine 做的事情是把 Windows 的 PE 文件加载起来把 kernel32、user32、gdi32 这些 DLL 的调用映射到 Linux/macOS 的系统调用上。它不是模拟器不模拟 Windows 内核而是重新实现了一套 API。所以 Wine 的兼容性取决于 API 覆盖度覆盖不到的地方就得靠补丁或者替代实现。Wine 的目录结构里drive_c是模拟的 C 盘注册表是模拟的注册表但底层文件系统还是宿主机的。这种设计让 Windows 程序以为自己在 Windows 上实际上读写的是宿主机文件。好处是性能接近原生坏处是路径映射和权限问题经常让人头疼。Wine 还有一个常被忽略的组件Wine Gecko和Wine Mono。前者提供 HTML 渲染能力后者提供 .NET 运行时。很多安装程序依赖它们如果没装会出现界面空白或者安装中断。热词里“wine gecko 官方正版下载”能上热搜说明踩这个坑的人不少。2.4 DXMTDirect3D 到 Metal 的桥梁DXMT 是 Direct3D 到 Metal 的转换层主要服务于 macOS 和 iOS 这类只能用 Metal 的平台。它把 D3D11 和部分 D3D12 调用翻译成 Metal 调用让 Windows 游戏和图形程序能在苹果生态里跑起来。和 DXVK 转 Vulkan 不同DXMT 直接转 Metal少了一层理论上延迟更低。但 Metal 和 D3D 的模型差异不小比如资源绑定、着色器编译、命令队列管理都需要做映射。DXMT 在这块做了不少工作但也不是所有 D3D 特性都能覆盖遇到不支持的调用会回退或者报错。2.5 平台适配层iOS 和桌面端的差异iOS 和桌面 Linux/macOS 最大的区别是沙箱和权限。iOS 应用不能随意 fork 进程不能动态加载未签名的库不能访问任意路径。这意味着 Wine 和 FEX-Emu 在 iOS 上不能照搬桌面端的做法需要把很多组件静态链接进去或者用 iOS 允许的方式加载。热词里“ios 开发者模式”“ios 自动化”“uniapp 使用 ios 原生插件”这些说明很多人在 iOS 上做开发和调试。Madeira 如果要上 iOS必须解决签名、沙箱、JIT 权限这几个问题。JIT 在 iOS 上默认是禁止的除非开启特定权限或者用解释模式这会直接影响 FEX-Emu 的性能。3. 核心细节解析每个环节的关键参数与操作要点3.1 FEX-Emu 的配置项怎么调FEX-Emu 的配置文件通常在~/.fex-emu/Config.json几个关键项值得关注。RootFS指向一个 x86-64 的根文件系统里面放的是目标程序依赖的库。这个 RootFS 可以是 Ubuntu、Debian 或者别的发行版的 x86-64 版本FEX-Emu 会在翻译指令的同时把库调用也重定向过去。ThunkHostLibs和ThunkGuestLibs用于处理宿主库和客户库的映射。比如程序调用了libGL.soFEX-Emu 需要知道是把它映射到宿主机的libGL.so还是 RootFS 里的版本。配错了会出现符号找不到或者版本冲突。Multiblock和SMCChecks影响翻译缓存的粒度。Multiblock 开启后FEX-Emu 会把多个基本块合并翻译减少跳转开销但会增加编译时间。SMCChecks 用于处理自修改代码开启后兼容性更好但性能有损失。我的经验是先默认配置跑通再根据性能瓶颈逐项调整。提示FEX-Emu 的日志级别可以通过FEX_LOG_LEVEL环境变量控制。排查问题时设成info或debug能看到指令翻译和系统调用的详细过程。日志量很大建议重定向到文件再分析。3.2 Wine 前缀的创建与优化Wine 的“前缀”是一个独立的环境里面有自己的注册表、C 盘和配置。创建前缀用WINEPREFIX/path/to/prefix winecfg第一次运行会初始化。建议每个程序用独立前缀避免 DLL 冲突。前缀创建后几个优化点一是安装winetricks用它装 Gecko、Mono、字体和常用运行库。二是调整winecfg里的 Windows 版本有些程序在 Win7 模式下比 Win10 模式更稳。三是设置DXVK或DXMT的 DLL 覆盖把d3d11、dxgi这些设为原生或内建取决于你用哪套图形转换。字体乱码是高频问题。Wine 默认字体不全中文程序容易出现方块。解决办法是把 Windows 的字体复制到前缀的drive_c/windows/Fonts目录或者用winetricks corefonts装基础字体。热词里“wine 乱码”“wine 栏是乱码”反复出现说明这个问题很普遍。3.3 DXMT 的部署与着色器缓存DXMT 的部署方式取决于平台。在 macOS 上通常把编译好的d3d11.dll、dxgi.dll、winemetal.dll放到 Wine 前缀的system32目录然后在winecfg的库设置里把d3d11和dxgi设为原生。DXMT 还依赖winemetal这个库负责和 Metal 驱动通信不能漏。着色器编译是 DXMT 的性能关键。Metal 的着色器编译比较慢DXMT 会把编译结果缓存起来下次直接加载。缓存目录一般在~/Library/Caches或者前缀目录下。如果缓存损坏会出现画面异常或者启动失败删掉缓存重新编译即可。注意DXMT 对 D3D12 的支持还在完善中部分游戏用 D3D12 模式会崩溃。遇到这种情况可以在游戏设置里切到 D3D11或者用启动参数强制指定。3.4 iOS 端的特殊处理iOS 上跑这套东西最大的限制是不能动态生成可执行代码。FEX-Emu 的 JIT 依赖mmap分配可执行内存iOS 默认不允许。变通方案是用解释模式性能会下降不少但能跑起来。另一个方案是利用 iOS 的开发者模式和相关权限但这需要特定的签名和配置不是普通用户能随便开的。Wine 在 iOS 上也不能直接跑需要把 Wine 的库静态链接到一个 iOS 应用里或者用 iOS 允许的动态库加载方式。热词里“ios 开发者模式”“ios 26.3.1 怎么开发者模式”说明很多人在尝试这条路但门槛不低。文件系统也是问题。iOS 应用只能访问自己的沙箱目录Wine 的drive_c需要映射到沙箱内。程序如果硬编码了C:\Program Files这类路径需要做重定向。这部分工作量大且容易出兼容性问题。4. 实操过程从零搭一套可运行的兼容环境4.1 环境准备与依赖安装先确定目标平台。以 Linux ARM64 桌面为例需要装好基础编译工具、Python、CMake、Ninja以及 FEX-Emu 和 Wine 的构建依赖。FEX-Emu 的依赖包括libssl-dev、libfmt-dev、libepoxy-dev等Wine 的依赖更多libx11-dev、libfreetype-dev、libasound2-dev这些都要。如果不想自己编译可以用发行版打包好的版本。但兼容层项目更新快打包版本往往滞后遇到问题不好排查。我的建议是至少把 FEX-Emu 和 DXMT 自己编译一遍Wine 可以用系统包出问题再换自编译版本。RootFS 的准备下载一个 x86-64 的 Ubuntu 或者 Debian 根文件系统解压到~/.fex-emu/RootFS/Ubuntu这类目录。里面要有lib/x86_64-linux-gnu下的基础库以及目标程序需要的依赖。可以用debootstrap生成也可以直接下载现成的 rootfs 压缩包。4.2 FEX-Emu 的编译与配置编译 FEX-Emu 的典型流程git clone https://github.com/FEX-Emu/FEX.git cd FEX git submodule update --init --recursive mkdir build cd build cmake -DCMAKE_BUILD_TYPERelease -DENABLE_LTOON .. make -j$(nproc) sudo make installENABLE_LTO开启链接时优化能提升性能但编译时间变长。如果内存不够可以关掉。编译完成后FEXInterpreter和FEXBash是主要入口。FEXBash会启动一个 x86-64 的 shell在里面可以像在 x86 机器上一样操作。配置 RootFS 路径export FEX_ROOTFS~/.fex-emu/RootFS/Ubuntu export FEX_APP_CONFIG~/.fex-emu/AppConfig然后运行FEXBash如果能进入 shell 并执行uname -m显示x86_64说明翻译层工作正常。4.3 Wine 前缀的创建与程序安装在 FEXBash 里创建 Wine 前缀export WINEPREFIX~/.wine-madeira winecfgwinecfg会弹出配置窗口第一次运行会初始化前缀。如果窗口没出来检查 X11 转发或者 Wayland 兼容性。初始化完成后用winetricks装依赖winetricks corefonts vcrun2019 dotnet48vcrun2019和dotnet48是很多程序的硬依赖提前装好能省不少事。装完后用wine setup.exe安装目标程序。安装过程中如果卡住看终端输出通常是某个 DLL 缺失或者 API 没实现。4.4 DXMT 的集成与图形测试DXMT 的编译需要 Xcode 和 Metal 工具链在 macOS 上git clone https://github.com/3Shain/dxmt.git cd dxmt mkdir build cd build cmake -DCMAKE_BUILD_TYPERelease .. make -j$(nproc)编译产物包括d3d11.dll、dxgi.dll、winemetal.dll。把它们复制到 Wine 前缀的drive_c/windows/system32然后在winecfg的库设置里把d3d11和dxgi设为原生。运行一个 D3D11 测试程序比如dxdiag或者简单的 3D demo看是否能正常渲染。如果画面黑屏或者花屏先检查winemetal是否加载成功。可以用WINEDEBUGd3d11看日志确认调用是否走到了 DXMT。着色器编译失败的话日志里会有 Metal 编译错误根据错误信息调整。4.5 性能调优与参数记录性能调优从几个方向入手。CPU 侧FEX-Emu 的Multiblock和SMCChecks影响翻译效率可以对比开启前后的帧率。内存侧RootFS 放在 SSD 上比 HDD 快很多因为翻译缓存和库加载都依赖磁盘 IO。图形侧DXMT 的着色器缓存要保留删了会重新编译首次运行卡顿明显。我实测下来一个中等复杂度的 D3D11 程序在 ARM64 桌面 FEX-Emu Wine DXMT 这套组合下帧率大概是原生 x86-64 Windows 的 40% 到 60%。瓶颈主要在指令翻译和图形转换。如果程序是 CPU 密集型FEX-Emu 的开销更明显如果是 GPU 密集型DXMT 的转换开销占比更大。5. 常见问题与排查技巧实录5.1 Wine 乱码与字体问题速查现象可能原因解决办法界面中文显示方块缺少中文字体复制 Windows 字体到前缀 Fonts 目录菜单栏乱码字体映射错误用 winetricks 装 corefonts或改注册表字体替换安装程序文字重叠DPI 设置不对winecfg 里调整 DPI 为 96 或 120部分文字显示为问号编码不匹配设置LANGzh_CN.UTF-8检查程序编码字体问题的根源是 Wine 默认只带少量开源字体中文覆盖不全。最稳的办法是从 Windows 系统里复制simsun.ttc、msyh.ttc这些字体到前缀的drive_c/windows/Fonts然后在注册表里把默认字体替换成它们。注册表路径是HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\FontSubstitutes。5.2 FEX-Emu 启动失败的排查路径启动失败通常分几种一是 RootFS 路径不对FEX-Emu 找不到 x86-64 的库二是宿主库和客户库冲突符号解析失败三是权限问题RootFS 目录不可读或者不可执行。排查时先看FEX_LOG_LEVELdebug的输出确认 RootFS 是否加载成功。如果报library not found检查 RootFS 里是否有对应的.so文件。如果报symbol not found可能是版本不匹配换一个 RootFS 或者装对应版本的库。还有一种情况是程序启动了但立刻退出没有任何输出。这通常是程序依赖的某个库在翻译过程中出了问题可以用strace跟踪系统调用看最后卡在哪里。FEX-Emu 对某些系统调用的处理还不完善遇到不支持的调用会直接终止。5.3 DXMT 图形异常的定位方法图形异常的表现很多黑屏、花屏、闪烁、帧率骤降。定位时先确认 DXMT 是否真的生效。用WINEDEBUGdxgi,d3d11看日志如果日志里出现DXMT字样说明调用走到了 DXMT如果还是wined3d说明 DLL 覆盖没生效。黑屏最常见的原因是着色器编译失败。Metal 的着色器语言和 HLSL 差异不小DXMT 的转换器不是所有语法都支持。日志里会有具体的编译错误根据错误改着色器或者换 D3D 特性级别。花屏通常是资源格式不匹配比如纹理格式在 Metal 里没有对应项DXMT 会回退到软件渲染导致画面异常。帧率骤降可能是着色器缓存失效每次运行都重新编译。检查缓存目录是否可写或者缓存文件是否被清理。另外Metal 的命令队列提交方式也会影响性能DXMT 有相关配置项可以调整但需要根据具体程序调。5.4 iOS 端特有的坑iOS 上跑这套东西除了前面说的 JIT 限制和沙箱问题还有几个坑。一是签名所有动态库都要签名未签名的库加载会失败。二是内存限制iOS 对应用内存有上限FEX-Emu 的翻译缓存和 Wine 的前缀会占不少内存容易触发系统杀进程。三是后台策略iOS 应用切到后台很快会被挂起长时间运行的任务需要特殊处理。热词里“ios 无感”“ios 无感漏洞”这类词我不确定具体指什么也不建议往那个方向深究。做 iOS 开发还是走正规路径用开发者模式和相关权限别碰来路不明的工具。5.5 国产化系统上的适配经验麒麟、统信这些国产化系统底层也是 Linux但库版本和桌面环境有自己的特点。Wine 在这些系统上跑常见问题是缺少依赖库或者库版本太老。热词里“麒麟 wine 助手”“统信 wine windows 兼容组件下载”说明有专门的适配工具这些工具通常会打包好依赖和配置省去手动折腾。我的建议是先在标准 Ubuntu 上把流程跑通再迁移到国产化系统。迁移时重点检查库版本和桌面环境的差异比如 X11 和 Wayland 的兼容性输入法框架的对接字体配置的路径。这些细节在标准系统上不是问题在定制系统上可能就是拦路虎。6. 几个容易被忽略的细节与个人体会6.1 关于 RootFS 的选择RootFS 用哪个发行版对兼容性影响很大。Ubuntu 的库比较新适合跑新程序Debian 稳定但库旧适合老程序。如果程序依赖特定版本的 glibcRootFS 的 glibc 版本必须匹配或者更高。我一般准备两个 RootFS一个 Ubuntu 22.04一个 Debian 11根据程序切换。RootFS 不要放在网络文件系统上翻译缓存和库加载对 IO 延迟敏感。放在本地 SSD 上体验会好很多。RootFS 的权限也要注意FEX-Emu 需要读取和执行权限如果权限不对会报莫名其妙的错误。6.2 Wine 前缀的备份与迁移调好的 Wine 前缀很宝贵重装系统或者换机器时直接复制前缀目录就能迁移。但要注意前缀里的注册表里有绝对路径迁移后可能需要用wine regedit改路径。另外前缀里的 DLL 覆盖设置和 winetricks 装的组件都在前缀内部复制过去就能用。我习惯给每个调好的前缀打个压缩包标注程序名和版本。下次遇到同类程序直接解压复用省去重新配置的时间。这个习惯在批量适配时特别有用。6.3 性能预期要合理兼容层不是魔法性能损失是必然的。指令翻译有开销API 转换有开销图形转换也有开销。指望跑出原生性能不现实。我的经验是2D 程序和老游戏体验可以接受3D 大作和性能敏感的程序能跑起来就不错了。如果性能是硬需求考虑用原生 ARM 版本或者找专门优化过的移植版。兼容层适合的是那些没有原生版本、又必须用的程序。定位清楚了心态就平和了。6.4 社区资源怎么用这类项目的社区很活跃但信息分散。FEX-Emu 的 Discord、Wine 的论坛、DXMT 的 GitHub Issues都是找答案的地方。提问前先搜很多问题别人已经踩过。提问时带上日志和配置别只写“跑不起来”那样没人能帮你。热词里那些下载链接和工具来源不明的不要碰。兼容层项目都是开源的从官方仓库拿代码和二进制别用来路不明的打包版。安全第一省事第二。最后分享一个小技巧调试图形问题时先用一个最简单的 D3D 程序验证链路比如微软的 DirectX SDK 里的示例。链路通了再上目标程序。这样能把问题范围缩小避免一上来就被复杂程序的报错淹没。