AI写代码总爱自作聪明？用AGENTS.md和Prompt工程治好它
2026/10/1 14:02:50
1. 项目缘起：为什么要在 iOS 上折腾 Wine
第一次看到 "Madeira" 这个代号，很多人会以为是某个旅游项目或者葡萄酒品牌。但在我们这圈子里，它指向的是一件更硬核的事情：在 iOS 设备上跑 Windows 应用。热搜词里那一串 Wine、FEX-Emu、DXMT、x86-64 已经暴露了它的技术底色——这是一个把 x86-64 指令翻译、Windows API 兼容、图形指令转换三层能力叠在一起，最终落到 iOS 沙盒里的兼容层工程。
先说清楚它解决什么问题。iOS 生态长期是封闭的，App Store 上架审核严格，很多老旧的 Windows 工具、行业软件、单机游戏根本没有 iOS 版本。而 Wine 这类兼容层做的事情，是在不修改原程序的前提下，把 Windows 的系统调用翻译成宿主系统的调用。放到 iOS 上，难度直接翻倍：CPU 架构是 ARM64，系统调用是 Darwin 内核那一套，图形接口是 Metal，沙盒权限又卡得死。所以 "Madeira" 这类项目本质上是在做三件事的缝合——指令集翻译、API 转译、图形后端重映射。
适合谁来读这篇？三类人。第一类是 iOS 开发者，想搞清楚跨架构兼容到底卡在哪；第二类是折腾党，手里有越狱设备或者开发者账号，想自己跑起来试试；第三类是技术观察者，想理解 Wine 生态在移动端的最新进展。不管你是哪一类，我都会把原理、步骤、坑点讲透，能抄作业的地方直接给方案。
需要提前说明的是，iOS 上的兼容层运行依赖一定的系统权限和签名机制，普通未越狱设备能做的事情有限，本文讨论的是技术原理和开发者视角下的实践路径，不涉及任何绕过系统安全机制的违规操作。
2. 核心技术拆解：三层翻译栈到底怎么协作
2.1 FEX-Emu：把 x86-64 指令翻译成 ARM64
Wine 本身不负责 CPU 指令翻译。在 Linux 桌面上，x86 程序跑在 x86 CPU 上，Wine 只需要处理 API 层。但 iOS 设备是 ARM64 架构，Windows 程序编译出来是 x86 或 x86-64 指令，中间必须有一层动态二进制翻译。这就是FEX-Emu的位置。
FEX-Emu 的工作方式是 JIT（即时编译）：程序执行到一段 x86 指令时，FEX 把它翻译成等价的 ARM64 指令块，缓存起来，下次再执行到同一段就直接用缓存。这个过程对上层程序是透明的。它的难点在于 x86 和 ARM 的内存模型不一致——x86 是强内存序（TSO），ARM 是弱内存序，多线程程序里如果不插入足够的内存屏障，就会出现诡异的竞态 bug。FEX 通过在每个内存访问点插入屏障指令来保证语义正确，代价是性能损失。
实测下来，FEX 的翻译开销在计算密集型任务上大约是原生性能的 40% 到 70%，具体取决于指令混合比例。浮点密集的代码损失更大，因为 x86 的 x87 和 SSE 指令要映射到 ARM 的 NEON，寄存器映射和舍入模式都要小心处理。
2.2 Wine：Windows API 的翻译层
指令翻译解决了"CPU 看不懂"的问题，但程序调用的CreateFileW、RegOpenKeyEx、MessageBoxA这些 Windows API，iOS 上根本没有。Wine 的职责就是实现一套同名同签名的 API，内部转成 POSIX 调用。
Wine 的架构是分层的：最上面是 DLL 实现（kernel32、user32、gdi32 等），中间是 ntdll（负责系统调用和底层对象管理），最下面是宿主适配层。在 iOS 上，ntdll 要对接的是 Darwin 的 Mach 内核接口，而不是 Linux 的 syscall。这意味着 Wine 的移植工作量不小，尤其是线程和同步对象——Windows 的 Event、Mutex、Semaphore 语义和 POSIX 的 pthread 原语不完全对应，需要额外维护状态机。
热搜里出现的 "wine 乱码" 和 "wine 栏是乱码"，八成是字体和编码问题。Wine 默认用系统字体渲染，如果宿主没有装对应的中文字体，或者 locale 设置不对，菜单栏就会显示方块。解决办法通常是往 Wine 的字体目录里塞一份中文字体，再改注册表里的字体替换项。
2.3 DXMT：把 Direct3D 翻译成 Metal
图形是另一个大坑。Windows 游戏和软件大量使用 Direct3D 9/10/11，而 iOS 只认 Metal。中间的翻译层有好几个选择：DXVK 走 Vulkan 路线，但在 iOS 上 Vulkan 支持不完整；DXMT则是直接把 D3D 翻译成 Metal，省掉了 Vulkan 这一跳。
DXMT 的核心工作是着色器翻译：把 HLSL 编译出的 DXBC 字节码，反编译再重新生成 Metal Shading Language。这个过程涉及资源绑定模型的重映射——D3D 的 constant buffer、texture、sampler 绑定槽位和 Metal 的 argument buffer 模型差异很大，DXMT 需要维护一张映射表，并在每帧更新时同步状态。渲染状态（混合模式、深度测试、剔除）也要逐个对应到 Metal 的 render pipeline state。
性能上，DXMT 的翻译是预编译 + 缓存的：第一次遇到某个着色器会编译并缓存，后续直接复用。所以首次运行游戏时会有明显的卡顿，之后就顺畅了。这也是为什么很多兼容层项目第一次启动特别慢，属于正常现象。
3. 环境准备：iOS 侧需要哪些前置条件
3.1 设备与系统版本的选择
不是所有 iOS 设备都能跑。首先需要ARM64 架构，这意味着 iPhone 5s 之后的机型基本都满足。其次，兼容层运行需要一定的系统权限，普通零售版 iOS 的沙盒限制很严，能做的事情有限。开发者模式下可以侧载自签名应用，但 JIT 权限（动态生成可执行代码）在未越狱设备上默认是关闭的，而 FEX-Emu 的 JIT 恰恰依赖这个能力。
所以现实中的路径通常是：越狱设备 + 开发者账号，或者使用支持 JIT 的调试环境。热搜里 "ios 开发者模式"、"ios 26.3.1 怎么开发者模式" 这类词，说明很多人卡在第一步——不知道怎么打开开发者模式。iOS 16 之后，开发者模式在"设置 - 隐私与安全性"里，需要先用 Xcode 或者配置描述文件触发一次才会出现。
3.2 签名与证书配置
侧载应用需要签名。免费开发者账号签名的应用7 天过期，过期后要重新签。付费账号（99 美元/年）可以签一年。热搜里 "免费证书 ios"、"xcode 从证书配置到上架全流程" 反映的就是这个痛点。
签名流程大致是：生成 Certificate Signing Request → 在开发者后台创建证书 → 下载并导入钥匙串 → 创建 App ID → 创建 Provisioning Profile → Xcode 里配置签名。这套流程走一遍大概半小时，但第一次做容易在证书类型上搞混（Development 和 Distribution 是两回事）。
提示：自签名应用的 Bundle ID 必须和 Provisioning Profile 里的一致，否则安装会失败，报错通常是 "Unable to Install" 或者签名无效。
3.3 依赖组件的准备
Wine 运行还需要一些运行时组件。热搜里 "wine gecko 官方正版下载" 指的是 Wine 的 HTML 渲染引擎 Gecko，很多安装程序用它来显示界面。没有 Gecko，某些安装向导会直接崩溃。另外还有 Mono，用于 .NET 程序的兼容。
在 iOS 上，这些组件需要预先打包进应用 bundle，不能像桌面版那样运行时下载（沙盒限制）。所以构建流程里要把 Gecko 和 Mono 的 msi 包解压后放进指定目录。
4. 实操流程：从零构建一个可运行的兼容层
4.1 构建 FEX-Emu 的 ARM64 版本
第一步是交叉编译 FEX-Emu。它本身是 C++ 项目，用 CMake 构建。关键配置项是目标架构和 JIT 后端：
cmake -DCMAKE_TOOLCHAIN_FILE=ios-arm64-toolchain.cmake \ -DENABLE_JIT=ON \ -DENABLE_CORECL=OFF \ -DCMAKE_BUILD_TYPE=Release \ ..ENABLE_JIT必须打开，否则只能解释执行，性能会掉到个位数帧率。ENABLE_CORECL是另一个 JIT 后端，iOS 上兼容性一般，建议关掉。
编译产物是一个静态库，链接进主应用。注意 iOS 对可执行内存页有 W^X 限制（要么可写要么可执行，不能同时），FEX 的 JIT 需要申请可执行内存，这要求应用有对应的 entitlement。没有这个 entitlement，JIT 会直接失败。
4.2 移植 Wine 的 Darwin 适配层
Wine 的源码树里，dlls/ntdll/unix/目录是宿主适配层。Linux 版本用 syscall，Darwin 版本要用 Mach 接口。主要改动点：
- 线程创建：用
pthread_create替代clone，但要注意栈大小和 guard page 的设置。 - 同步对象：Windows 的
WaitForSingleObject要映射到pthread_cond_timedwait，超时处理要小心时钟源差异（Windows 用 100ns 单位，POSIX 用 timespec）。 - 文件系统：Windows 路径
C:\要映射到 iOS 沙盒的 Documents 目录，路径分隔符和大小写敏感性都要处理。
这部分工作量最大，也是最容易出 bug 的地方。实测中，文件 API 的兼容性决定了多少程序能跑起来——很多安装程序第一步就是往C:\Program Files写文件，路径映射错了直接失败。
4.3 集成 DXMT 并配置 Metal 后端
DXMT 作为 Wine 的图形驱动，需要编译成d3d11.dll、dxgi.dll等模块，替换 Wine 自带的实现。编译时指定 Metal 后端：
meson setup build -Dd3d11=true -Ddxgi=true -Dmetal=true运行时，Wine 通过注册表指定使用 DXMT：
[HKEY_CURRENT_USER\Software\Wine\DllOverrides] "d3d11"="native" "dxgi"="native"native表示用我们编译的版本，而不是 Wine 内置的。这一步配错的话，程序会回退到 Wine 的软件渲染，画面会非常卡。
4.4 打包与部署
最后把所有产物打包成一个 iOS 应用：主程序负责初始化 FEX、加载 Wine 的 PE 文件、启动目标程序。资源文件（Gecko、Mono、字体）放进 bundle。用 Xcode 签名后安装到设备。
首次启动会比较慢，因为要初始化 JIT 缓存和着色器缓存。建议先跑一个简单的 Windows 程序（比如记事本）验证链路是否通，再上复杂的游戏。
5. 常见问题与排查技巧实录
5.1 中文乱码的三种成因与修复
热搜里 "wine 乱码" 出现频率很高，我踩过的坑主要有三类：
| 现象 | 成因 | 修复方法 |
|---|---|---|
| 菜单栏显示方块 | 缺少中文字体 | 往drive_c/windows/Fonts放一份中文字体，注册表设置替换 |
| 程序界面文字乱码 | locale 未设置 | 设置环境变量LANG=zh_CN.UTF-8 |
| 输入框无法输入中文 | 输入法未对接 | 需要 Wine 的 IME 模块支持，iOS 上较难，建议用英文输入 |
字体替换的注册表项是：
[HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\FontSubstitutes] "MS Shell Dlg"="WenQuanYi Micro Hei" "MS Shell Dlg 2"="WenQuanYi Micro Hei"5.2 JIT 权限失败的排查
如果启动时报 "Cannot allocate executable memory"，说明 JIT entitlement 没生效。检查步骤：
- 确认签名时带了
com.apple.security.cs.allow-jit这个 entitlement。 - 确认设备已开启开发者模式。
- 如果是越狱设备，确认没有开启某些限制 JIT 的插件。
这个问题的表现是程序启动后立刻崩溃，日志里能看到mprotect失败。
5.3 图形相关的典型故障
DXMT 相关的故障通常表现为黑屏、花屏或者帧率极低。排查思路：
- 黑屏：着色器编译失败。打开 DXMT 的日志，看有没有 "shader compile error"。常见原因是用了 Metal 不支持的 HLSL 特性。
- 花屏：纹理格式映射错误。D3D 的某些压缩纹理格式（如 BC7）在 Metal 上需要特殊处理。
- 帧率低：可能回退到了软件渲染。检查 DllOverrides 是否生效。
5.4 性能调优的几个实用技巧
- 开启着色器缓存：DXMT 支持把编译好的 Metal 着色器缓存到磁盘，第二次启动会快很多。
- 限制分辨率：iOS 设备屏幕分辨率很高，全分辨率渲染压力大。可以在 Wine 里设置虚拟桌面分辨率，降低渲染负担。
- 关闭不必要的后台进程：iOS 内存管理严格，后台应用会挤占内存，导致兼容层被系统杀掉。
6. 影响范围与生态观察
6.1 对 iOS 开发者的启示
这套技术栈的价值不只在"跑 Windows 程序"。FEX-Emu 的指令翻译思路，可以用于跨架构的代码迁移；DXMT 的图形翻译，对做跨平台渲染的团队有参考意义。热搜里 "uniapp 使用 ios 原生插件"、"ios 自动化" 这些词，说明移动端开发者对底层能力的渴求一直存在。
6.2 对 Wine 生态的推动
Wine 在桌面端已经相当成熟，但移动端一直是空白。Madeira 这类项目把 Wine 的能力延伸到了 iOS，虽然目前还处于早期阶段，但方向是明确的。热搜里 "麒麟 wine 助手"、"统信 wine windows 兼容组件下载" 反映的是国内 Linux 发行版对 Wine 的集成需求，这些经验反过来也能滋养移动端的移植工作。
6.3 现实中的限制
必须承认，iOS 上的兼容层离"开箱即用"还有距离。签名限制、JIT 权限、性能损耗、兼容性覆盖，每一个都是硬骨头。普通用户想在自己手机上跑 Windows 游戏，目前还是折腾大于实用。但对于开发者和技术爱好者来说，这套东西的价值在于验证了可行性，并且把关键路径上的坑都趟了一遍。
我在实际测试中的体会是，这套方案最适合的场景是轻量级的 Windows 工具类程序，比如老版本的行业软件、单机小工具。大型 3D 游戏虽然能跑，但帧率和稳定性还达不到可玩的程度。如果你只是想验证某个 Windows 程序能不能在 iOS 上跑起来，按照上面的流程走一遍，大概率能得到答案。至于性能优化和兼容性打磨，那是后续持续迭代的事情。