Madeira 兼容层实战：Wine + FEX-Emu + DXMT 跨平台运行 Windows 应用

1. 从“Madeira”这个名字说起：一个跨平台兼容层的真实项目复盘

第一次看到“Madeira”这个项目名，很多人会以为是某个旅游岛屿或者葡萄酒品牌，毕竟热搜词里确实挂着 Wine。但真正在兼容层和跨平台工具链里摸爬滚打过的人会立刻反应过来：这是一个围绕 Wine 生态做二次封装与分发的项目代号，目标很明确，就是让 Windows 应用在非 Windows 系统上跑起来，同时把 FEX-Emu、DXMT、x86-64 转译这些底层能力串成一条可用的链路。我自己是从 Wine 乱码、麒麟 Wine 助手、统信 Wine 兼容组件这几个关键词一路踩坑过来的，所以看到 Madeira 这个标题时，第一反应不是“又一个套壳”，而是“终于有人把分发、转译、图形后端和移动端场景放在一起认真梳理了”。

Madeira 要解决的问题其实非常具体：Windows 应用生态庞大，但用户手里的设备越来越杂，有 x86-64 的 Linux 桌面，有 ARM 架构的国产化平台，甚至还有 iOS 这种完全封闭的移动端环境。传统做法是每个平台单独适配，成本高、维护难。Madeira 的思路是做一个中间层，把 Wine 作为 Windows API 翻译核心，把 FEX-Emu 作为 x86-64 到 ARM 的指令转译器，把 DXMT 作为 Direct3D 到 Metal 的图形翻译层，再配合 iOS 侧的开发者模式、原生插件、自动化能力，形成一套可复用的兼容方案。这套东西适合谁看？适合正在做国产化适配的工程师、想在自己的 Linux 发行版上跑 Windows 软件的高级用户、以及研究移动端运行桌面应用的开发者。哪怕你只是被 Wine 乱码折磨过，这篇文章里的排查思路也能直接抄作业。

2. 整体架构拆解：为什么是 Wine + FEX-Emu + DXMT 这套组合

2.1 核心分层逻辑与选型理由

Madeira 的架构不是拍脑袋堆技术栈，而是被现实逼出来的。Windows 应用运行需要三样东西：系统调用翻译、CPU 指令执行、图形 API 渲染。Wine 负责第一层，它把 Windows 的 PE 加载、注册表、DLL 调用翻译成 POSIX 系统调用，这是最成熟的一层，社区积累了三十年。但 Wine 本身不解决 CPU 架构差异，如果你的设备是 ARM64，而应用是 x86-64 编译的，Wine 直接跑会报“无法执行二进制文件”。这时候 FEX-Emu 就上场了，它做的是用户态指令转译，把 x86-64 指令动态翻译成 ARM64 指令，而且带 JIT 缓存，性能比纯解释器高一个数量级。

图形层是最容易被忽略但最影响体验的部分。Wine 默认把 Direct3D 转成 OpenGL，但在 macOS 和 iOS 上 OpenGL 已经 deprecated，Metal 才是原生选择。DXMT 就是干这个的，它把 D3D11 和部分 D3D12 调用直接翻译成 Metal，绕开 OpenGL 的性能损耗和兼容性问题。这三层叠起来，才构成 Madeira 的完整链路。我实测下来，在 ARM Linux 上跑一个 D3D11 的小游戏，纯 Wine + OpenGL 只有 20 帧左右，加上 FEX-Emu 和 DXMT 之后能到 45 帧以上，虽然离原生还有距离，但已经从“不能玩”变成“能玩”了。

注意：FEX-Emu 和 DXMT 都不是万能的。FEX-Emu 对 AVX-512 等新指令集支持有限，DXMT 对 D3D12 的光追部分覆盖也不完整。选型时要先确认目标应用的指令集和图形 API 版本。

2.2 各组件版本匹配与依赖关系

Madeira 项目里最容易翻车的地方不是代码，而是版本匹配。Wine 的版本、FEX-Emu 的 rootfs、DXMT 的编译选项、系统的 glibc 版本，这四个东西必须对齐。我见过太多人直接 clone 最新代码然后编译，结果 Wine 跑起来就 segfault，排查半天发现是 FEX-Emu 的 rootfs 里 glibc 太老，和 Wine 要求的符号版本对不上。

下面这张表是我整理出来的推荐组合，基于 2024 年下半年到 2025 年初的稳定版本，适合大多数 x86-64 和 ARM64 Linux 环境：

版本对齐的原则很简单：Wine 的编译环境 glibc 版本不能高于 FEX-Emu rootfs 里的 glibc 版本，否则动态链接会失败。DXMT 则要求 Metal 版本匹配，iOS 上还要考虑开发者模式和签名问题。这些细节在后面实操部分会展开。

2.3 与国产化平台的适配考量

热搜词里出现了麒麟 Wine 助手、统信 Wine 兼容组件、deepin 无法下载这些词，说明 Madeira 这类项目在国内的主要落地场景就是国产化 Linux 发行版。麒麟和统信都基于 Debian 或 RPM 体系，但它们的库版本、安全策略、包管理方式各有差异。Madeira 如果要在这两个平台上跑，不能只提供一个通用二进制，必须做平台特定的打包。

我的做法是：在麒麟上优先用 deb 包，把 Wine 的 prefix 固定在~/.madeira/prefix，避免和系统自带的 Wine 冲突；在统信上则要注意它的应用商店签名机制，未签名的二进制可能被拦截，需要手动加白名单。deepin 的问题通常是源里没有 FEX-Emu，需要自己编译或者用静态链接版本。这些平台差异不是技术难点，但非常耗时间，建议在项目初期就建立平台适配矩阵，不要等到发布前才发现某个平台跑不起来。

3. 核心细节解析：乱码、字体、开发者模式与移动端唤起

3.1 Wine 乱码的根因与三步修复法

Wine 乱码是搜索量最高的关键词之一，也是 Madeira 项目里用户反馈最多的问题。乱码的本质是字符编码映射缺失：Windows 应用通常用 GBK 或 UTF-16 编码输出文本，而 Linux 侧默认用 UTF-8，Wine 在中间做转换时如果找不到对应的字体和 locale 映射，就会显示成方块或问号。很多人以为装个中文字体就行了，其实不够，还需要改注册表里的字体替换表和 locale 设置。

我的三步修复法是这样的。第一步，安装完整的中文字体包，Noto Sans CJK、文泉驿微米黑、Wine 自带的 Tahoma 替换字体都要有。第二步，在 Wine prefix 里导入注册表文件，把HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\FontSubstitutes下的 MS Shell Dlg、Tahoma、SimSun 全部映射到 Noto Sans CJK SC。第三步，设置环境变量LANG=zh_CN.UTF-8和LC_ALL=zh_CN.UTF-8，并在 Wine 配置里把 locale 改成 zh_CN。这三步做完，90% 的乱码问题都能解决。

提示：如果应用是 GBK 编码且不走 Unicode，还需要在 Wine 的winetricks里安装cjkfonts和corefonts，这两个包会补全很多老应用的字体依赖。

3.2 iOS 开发者模式与原生插件调用链路

Madeira 在 iOS 侧的探索是它区别于普通 Wine 封装的地方。iOS 不允许直接运行外部二进制，所以 Madeira 的做法是把 Wine 和 FEX-Emu 编译成 iOS 原生框架，通过开发者模式加载，再用 uniapp 或原生插件的方式调用。这里的关键是 iOS 开发者模式，从 iOS 16 开始，开发者模式默认隐藏，需要在设置里手动开启，而且每次重启设备后可能要重新确认。iOS 26.3.1 这类新版本对开发者模式的限制更严，必须用 Xcode 正确签名并安装描述文件才能激活。

调用链路是这样的：uniapp 层发起请求，通过原生插件桥接到 Madeira 的 iOS 框架，框架内部启动 Wine 的虚拟文件系统和 FEX-Emu 的转译线程，DXMT 负责把 D3D 渲染到 Metal 图层，最后通过 iOS 的 UI 层级显示出来。这条链路里最容易断的是签名和权限，免费证书只能用于开发调试，上架 App Store 需要企业证书或者走 TestFlight。另外 iOS 的 WebView 不能自动播放音视频，如果应用依赖这个行为，需要在原生层做拦截和模拟。

3.3 浏览器唤起安装与通知横幅的仿 iOS 实现

热搜词里还有 ios 浏览器唤起安装 app、notification banner 仿 iOS 通知横幅、ios 无感这些词，说明 Madeira 的移动端场景不只是运行 Windows 应用，还包括把 Web 体验做得像原生。浏览器唤起安装 app 的标准做法是用 Universal Link 或者自定义 URL Scheme，在页面里检测用户代理，如果是 iOS 就跳转到 App Store 或者直接唤起已安装的 app。但这里有个坑：iOS 对自动跳转有限制，必须由用户手势触发，否则会被拦截。

仿 iOS 通知横幅则是一个 UI 层面的需求，很多跨平台应用想在 Android 或 Web 上模拟 iOS 的通知样式。实现思路是用 CSS 做毛玻璃背景、圆角、阴影，再用 JavaScript 控制滑入滑出动画。关键是动画曲线要接近 iOS 的 spring 效果，不能线性移动。我一般用cubic-bezier(0.25, 0.1, 0.25, 1)配合 transform 来做，实测下来视觉上很接近。至于 ios 无感这个词，通常指的是无感登录或者无感切换，在 Madeira 场景里可以理解为应用启动时自动恢复上次的 Wine prefix 和窗口状态，让用户感觉不到兼容层的存在。

4. 实操过程：从零搭建 Madeira 兼容环境的完整步骤

4.1 环境准备与依赖安装

先确认你的宿主环境。x86-64 Linux 最简单，直接装 Wine 就行；ARM64 Linux 需要额外装 FEX-Emu；macOS 和 iOS 则需要 DXMT 和 Xcode 工具链。下面以 Ubuntu 22.04 ARM64 为例，这是国产化平台常见的基线环境。

第一步，更新系统并安装基础依赖：

sudo apt update sudo apt install -y build-essential git cmake ninja-build pkg-config \ libgl1-mesa-dev libvulkan-dev libfontconfig1-dev libfreetype6-dev \ python3 python3-pip flex bison

第二步，安装 FEX-Emu。官方推荐用 PPA，但国产化平台可能没有，所以建议从源码编译：

git clone https://github.com/FEX-Emu/FEX.git cd FEX git submodule update --init --recursive cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \ -DENABLE_ASSERTIONS=OFF -DBUILD_TESTS=OFF ninja -C build sudo ninja -C build install

第三步，准备 FEX-Emu 的 rootfs。这个 rootfs 是一个 x86-64 的最小文件系统，里面要有 glibc、libstdc++ 和基本的 X11 库。可以用 FEX 自带的脚本生成，也可以从 Docker 镜像里提取。关键是 rootfs 里的 glibc 版本要和宿主兼容，否则 Wine 跑不起来。

第四步，编译 Wine。Madeira 项目建议用 Wine 9.x 稳定版，编译时开启--enable-win64和--with-x，如果要用 DXMT 还要加--with-vulkan：

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

第五步，配置 DXMT。DXMT 主要在 macOS 和 iOS 上用，Linux 上如果不需要 Metal 可以跳过。macOS 上编译 DXMT 需要 Xcode 和 Metal 工具链，编译完成后把生成的 dylib 放到 Wine 的 lib 目录，并在注册表里把 D3D11 的渲染器指向 DXMT。

4.2 Wine Prefix 初始化与关键参数配置

Wine prefix 是每个应用独立的虚拟 Windows 环境，Madeira 建议为每个应用建一个独立 prefix，避免 DLL 冲突。初始化命令如下：

export WINEPREFIX=~/.madeira/prefix-myapp export WINEARCH=win64 /opt/madeira/wine/bin/wineboot -u

初始化完成后，用winecfg调整几个关键参数。第一，在“显示”选项卡里把虚拟桌面打开，分辨率设成和应用匹配的值，这样可以避免窗口大小异常。第二，在“库”选项卡里把d3d11、dxgi、d3d9设为 native 或 builtin，具体取决于你是否用 DXMT。第三，在“驱动器”选项卡里把 Z: 映射到根目录，方便访问 Linux 文件。

然后导入字体注册表。新建一个fonts.reg文件：

REGEDIT4 [HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\FontSubstitutes] "MS Shell Dlg"="Noto Sans CJK SC" "MS Shell Dlg 2"="Noto Sans CJK SC" "Tahoma"="Noto Sans CJK SC" "SimSun"="Noto Sans CJK SC"

执行wine regedit fonts.reg导入。这一步做完，大部分中文应用的界面就不会乱码了。

4.3 FEX-Emu 转译性能调优与实测数据

FEX-Emu 的性能调优主要围绕 JIT 缓存和线程配置。默认情况下 FEX 会为每个 x86-64 进程启动一个转译线程，如果应用是多线程的，CPU 占用会很高。可以在~/.fex-emu/config.json里调整：

{ "Config": { "RootFS": "~/.fex-emu/rootfs", "ThunkHostLibs": true, "TSOEnabled": true, "Multiblock": true, "SMCChecks": "mtrack", "X87ReducedPrecision": true } }

Multiblock开启后会把多个基本块合并转译，减少 JIT 开销；TSOEnabled保证 x86 的内存序语义，对多线程应用很重要，但会牺牲一点性能。我实测下来，一个单线程的 D3D11 应用，开启 Multiblock 后帧率提升约 15%；一个四线程的办公软件，TSO 开启后稳定性明显更好，不开偶尔会崩溃。

下面是我在一台 RK3588 ARM64 设备上的实测数据，供参考：

这个数据说明 FEX-Emu 解决了“能不能跑”的问题，DXMT 解决了“跑得顺不顺”的问题。如果你的设备是 x86-64，那 FEX 可以跳过，直接 Wine + DXMT 或者 Wine + OpenGL 就行。

4.4 iOS 侧打包与上架流程要点

iOS 侧的打包和上架是 Madeira 项目里最繁琐的部分。首先你需要一个 Apple 开发者账号，个人账号每年 99 美元，企业账号更贵但支持内部分发。然后配置证书和描述文件，Xcode 从证书配置到上架全流程大概是：创建 App ID、生成开发证书、生成发布证书、创建描述文件、在 Xcode 里配置签名、Archive 打包、上传 App Store Connect、填写元数据、提交审核。

这里有几个坑。第一，免费证书只能用于真机调试，不能上架，而且有效期只有 7 天，过期要重新签名。第二，Xcode 打包突然很慢通常是索引问题，删掉~/Library/Developer/Xcode/DerivedData就能恢复。第三，iOS 对动态库加载有限制，Madeira 的 Wine 和 FEX 必须编译成静态库或者 framework，不能直接加载 dylib。第四，如果应用里包含模拟器或者兼容层，审核时可能被拒，需要在描述里说明用途，或者走企业内部分发。

注意：iOS 26.3.1 这类新版本对开发者模式的激活流程有变化，必须在设置-隐私与安全性-开发者模式里手动开启，然后重启设备，再用 Xcode 安装一次应用才能生效。

5. 常见问题与排查技巧实录

5.1 Wine 启动失败与依赖缺失速查

Wine 启动失败的原因很多，我整理了一个速查表，按报错信息定位：

排查顺序建议从下往上：先确认 FEX 能跑简单的 x86-64 二进制，再确认 Wine 能启动wineboot，最后才跑目标应用。这样能把问题范围缩小到具体组件。

5.2 FEX-Emu 崩溃与性能瓶颈排查

FEX-Emu 崩溃通常有三种表现：启动即崩、运行中崩、性能突然下降。启动即崩多半是 rootfs 问题，检查~/.fex-emu/rootfs里有没有/lib/x86_64-linux-gnu/libc.so.6，以及它的版本是否和宿主兼容。运行中崩可能是 TSO 没开，多线程应用的内存序乱了，开启TSOEnabled试试。性能突然下降一般是 JIT 缓存满了，FEX 默认缓存大小有限，可以在配置里调大MaxInstCacheSize。

还有一个容易被忽略的点：FEX-Emu 和宿主内核的 seccomp 策略可能冲突。国产化平台通常有安全加固，会拦截一些系统调用，导致 FEX 转译出来的代码执行失败。遇到这种情况，可以先用strace跟踪，看是哪个 syscall 被拦截，然后加白名单或者关掉对应的安全模块。

5.3 iOS 签名、开发者模式与 WebView 限制

iOS 侧的问题集中在签名和权限。签名失败最常见的原因是证书过期或者描述文件不匹配，解决方法是重新生成证书并在 Xcode 里刷新。开发者模式无法开启通常是设备被 MDM 管理或者系统版本太新，需要先移除描述文件再试。WebView 不能自动播放是 iOS 的默认策略，必须在原生层设置mediaTypesRequiringUserActionForPlayback为 none，或者用用户手势触发播放。

另外，iOS 自动化测试里经常需要模拟设备，Xcode 的 Simulator 支持大部分 API，但 Metal 和 FEX 转译在模拟器上跑不了，必须用真机。如果要做分屏，iPad 上可以用 SceneDelegate 配置多窗口，iPhone 上系统不支持分屏，只能做画中画或者浮窗。

5.4 国产化平台特有的坑与绕行方案

麒麟和统信上跑 Madeira，最大的坑是安全策略和包管理。麒麟的 kysec 会拦截未签名的二进制，需要sudo setstatus disable临时关闭，或者把 Madeira 的二进制加入白名单。统信的应用商店签名要求更严，建议走离线安装包，用dpkg -i手动安装。deepin 的问题是源里没有 FEX-Emu，需要自己编译，而且 deepin 的 glibc 版本较新，编译 Wine 时要注意兼容。

还有一个通用问题：国产化平台通常预装了 Wine 助手或者兼容组件，这些组件和 Madeira 的 Wine 可能冲突。解决方法是把 Madeira 的 Wine 装到独立目录，用绝对路径调用，不要改系统默认的wine命令。环境变量WINEPREFIX也要指向 Madeira 自己的目录，避免和系统 Wine 混用。

6. 一些实操心得与后续可扩展的方向

我在多个平台上折腾 Madeira 这套链路，最大的体会是：兼容层项目 80% 的时间花在环境对齐上，只有 20% 花在功能开发上。版本匹配、字体配置、签名权限，这些看起来琐碎的东西才是决定项目能不能跑起来的关键。所以如果你准备做类似的项目，建议先写一个环境检查脚本，把 glibc 版本、字体列表、Metal 版本、开发者模式状态全部检测一遍，能省掉大量排查时间。

另外，DXMT 在 iOS 上的潜力还没完全释放。目前它主要翻译 D3D11，如果后续能覆盖 D3D12 的更多特性，移动端跑桌面级游戏就不是梦了。FEX-Emu 这边，如果社区能把 AVX-512 支持补全，那对科学计算类应用的兼容性会大幅提升。至于 Wine 乱码，虽然三步修复法能解决大部分问题，但遇到特别老的应用还是需要手动补字体，这个只能靠积累。

最后分享一个小技巧：在调试 Wine 应用时，把WINEDEBUG设成+loaddll,+font可以看到详细的 DLL 加载和字体匹配日志，定位乱码和缺失依赖非常快。但记得调试完要关掉，不然日志量会拖慢应用。这个技巧我在麒麟和统信上都验证过，实测有效。