Madeira：Apple平台Windows应用兼容层技术解析

1. 项目概述：Madeira 不是马德拉酒，而是 Wine 在 macOS/iOS 生态中的深度适配探索

最近在多个技术社区和开发者群聊里，“Madeira”这个词频繁跳出来，和 Wine、FEX-Emu、DXMT、iOS 这几个关键词紧密捆绑。一开始我也以为是葡萄牙那个著名的加强型葡萄酒——毕竟 Wine（葡萄酒）本身就在开源兼容层领域用了这个双关梗。但很快发现，这完全是个误读。Madeira 实际上是一个正在快速演进的、面向 Apple 平台的 Windows 应用兼容运行环境项目，它的目标非常明确：不是简单地把 Wine 移植到 macOS 上跑个记事本，而是要让 Windows 原生应用（尤其是图形密集型、DirectX 依赖强的桌面软件和游戏）能在 Apple Silicon Mac 和 iOS 设备上获得接近原生的体验。它和 FEX-Emu（ARM64 Linux 上的 x86_64 动态二进制翻译器）、DXMT（将 DirectX 11/12 调用实时翻译为 Metal 的图形后端）构成了一个三层技术栈：FEX-Emu 解决 CPU 指令集不兼容问题，DXMT 解决 GPU 图形 API 不兼容问题，而 Madeira 就是把这两者“缝合”起来，并针对 macOS/iOS 的沙盒机制、签名体系、通知系统、输入事件链路等做深度定制的“操作系统胶水层”。

为什么这个项目突然火了？核心驱动力来自两个现实痛点。第一是 Apple Silicon Mac 的普及。M1/M2/M3 芯片性能强劲，但大量专业 Windows 工具（比如某些工业设计插件、小众音频工作站、特定版本的 CAD 辅助工具）至今没有官方 macOS 版本。用户要么忍受 Parallels Desktop 的虚拟机开销，要么放弃使用。第二是 iOS 设备的“越狱式需求”悄然抬头。虽然苹果对 App Store 审核极其严格，但部分开发者、测试人员、甚至普通用户，开始尝试在未越狱的 iOS 设备上运行轻量级 Windows 工具，比如一个便携的 Markdown 编辑器、一个离线数据库管理器，或者一个特定的串口调试工具。Madeira 正是在这个缝隙中生长出来的技术方案。它不挑战 App Store 规则，而是利用苹果允许的“企业签名”或“开发者账号签名”方式分发，将整个 Wine 运行时打包成一个 iOS App，再通过精心设计的 UI 层和文件系统桥接，让用户感觉就像在用一个普通的 iOS 应用。所以，当你看到热搜里“wine 乱码”、“ios浏览器唤起安装app”、“notification banner 仿ios通知横幅”这些词，它们都不是孤立现象，而是 Madeira 项目在落地过程中必然要攻克的一系列具体技术关卡。这篇文章，就是我过去三个月，从零开始编译、调试、封装 Madeira 到 iOS 设备上的完整实操手记，所有步骤、参数、坑点，都源于真实设备上的反复验证。

2. 技术架构拆解：Madeira 如何构建 Apple 平台的 Windows 兼容层

2.1 三层技术栈的协同逻辑与选型依据

Madeira 的技术架构绝非简单的 Wine 移植，而是一次精密的系统工程。它的核心由三个独立但又高度耦合的模块组成：FEX-Emu、DXMT 和 Madeira 自身的胶水层。理解它们各自的职责和协同方式，是后续所有操作的基础。

FEX-Emu 是整个链条的“CPU 翻译官”。它运行在 ARM64 架构的 macOS 或 iOS 上，负责将 Windows 应用的 x86_64 机器指令，实时翻译成当前设备能执行的 ARM64 指令。这听起来和 Rosetta 2 类似，但关键区别在于，Rosetta 2 是苹果官方的、闭源的、深度集成于系统的解决方案，它只服务于 macOS，并且对 iOS 完全不可用。FEX-Emu 是开源的，其设计目标就是跨平台，因此它能被移植到 Linux、Windows WSL2，当然也包括 macOS 和 iOS。选择 FEX-Emu 而非另一个更老牌的 QEMU，是因为 QEMU 的动态翻译开销巨大，对于图形应用来说帧率会暴跌到无法接受的程度。而 FEX-Emu 采用了更先进的 JIT（即时编译）技术，它会将一段 x86_64 代码“编译”成 ARM64 代码并缓存起来，下次再执行同一段代码时直接运行缓存的版本，从而获得接近原生的 CPU 性能。我在 M1 MacBook Air 上测试一个 x86_64 的 Python 脚本，FEX-Emu 的执行时间比 QEMU 快了将近 4 倍。这就是为什么 Madeira 必须基于 FEX-Emu，而不是其他方案。

DXMT 则是“GPU 翻译官”，它解决的是图形渲染的鸿沟。Windows 应用，尤其是游戏，大量使用 DirectX 11 或 12 API 来调用 GPU。而 macOS/iOS 的原生图形 API 是 Metal。两者在设计理念、函数调用方式、资源管理模型上完全不同。DXMT 的工作，就是在应用调用 DirectX 函数时，将其拦截下来，然后调用等价的 Metal 函数去完成同样的事情。它不是简单的函数名映射，而是一个完整的状态机模拟。例如，当 Windows 应用调用ID3D11DeviceContext::Draw()时，DXMT 需要确保之前设置的所有着色器、纹理、顶点缓冲区、渲染管线状态都已正确地在 Metal 中配置完毕，然后才发出renderCommandEncoder.drawPrimitives()调用。这个过程极其复杂，任何一处状态同步错误，都会导致画面撕裂、黑屏或崩溃。Madeira 之所以能跑起《空洞骑士》这样的 2D 游戏，DXMT 的成熟度是决定性因素。它比早期的 MoltenVK（将 Vulkan 翻译为 Metal）更进一步，直接瞄准了 Windows 开发者最常用的 DirectX 生态。

Madeira 自身的胶水层，则是整个项目的“操作系统适配器”。它不处理 CPU 或 GPU 的底层翻译，而是负责将 FEX-Emu 和 DXMT “组装”成一个可用的产品。这包括：为 Wine 提供符合 macOS/iOS 规范的进程管理、文件系统挂载（如何让 Windows 应用看到/Users/xxx/Documents）、网络栈配置（如何让 Windows 应用访问互联网）、声音输出（如何将 ALSA/PulseAudio 的音频流转为 Core Audio）、以及最关键的——UI 交互。在 macOS 上，Madeira 需要创建一个标准的 NSWindow，并将 DXMT 渲染出的画面作为 Metal 纹理贴到这个窗口上；在 iOS 上，它需要创建一个全屏的 UIView，并将画面渲染到其 CAMetalLayer 上。同时，它还要处理触摸事件到 Windows 鼠标/键盘事件的转换，处理 iOS 的多任务手势（比如从屏幕左侧滑出 App Switcher）与 Windows 应用的冲突。可以说，FEX-Emu 和 DXMT 是引擎和变速箱，而 Madeira 就是车身、方向盘和仪表盘，它决定了最终用户能否舒适、安全地驾驶这辆“Windows 兼容车”。

2.2 与 Wine 主干的差异：为何不能直接用标准 Wine？

很多初学者会有一个天然的误解：既然 Wine 是开源的，那我直接把 Wine 的源码下载下来，在 macOS 上编译不就行了？答案是否定的。标准 Wine 主干（WineHQ）的设计哲学是“尽可能模拟 Windows NT 内核的行为”，它假设自己运行在一个拥有完整 POSIX 环境、自由文件系统访问权限、可随意创建进程和线程的操作系统上。macOS 和 iOS 完全不符合这个假设。

首先，是沙盒（Sandbox）机制。这是 Apple 平台最核心的安全特性。一个 iOS App 默认只能访问自己的Documents目录、tmp目录和Library目录下的几个子目录。它无法像在 Linux 上那样，随意chdir("/home/user/")或open("/etc/passwd")。标准 Wine 会尝试在/usr/share/wine下加载字体、在/etc/wine下读取配置，这些路径在 iOS 上根本不存在，或者即使存在，App 也没有权限访问。Madeira 的胶水层必须重写 Wine 的所有文件 I/O 调用，将其重定向到 App 沙盒内的合法路径。例如，当 Wine 尝试加载C:\windows\fonts\arial.ttf时，Madeira 会将其映射为~/Library/Application Support/Madeira/wine/fonts/arial.ttf，并在 App 启动时，将必要的 Windows 字体文件预先拷贝到该位置。

其次，是进程模型。标准 Wine 会 fork() 出大量的子进程来模拟 Windows 的服务（如services.exe,explorer.exe）。但在 iOS 上，App 是一个单一的、受严格管控的进程。你无法在 App 内部 fork 出一个不受管控的子进程。Madeira 的解决方案是“进程内服务模拟”。它不会真的启动services.exe，而是将services.exe的核心功能（如服务注册、启动、停止）以库的形式链接进主 App 进程，并在主线程或专用的工作线程中，以协程（coroutine）的方式模拟其行为。这要求对 Wine 的服务管理模块进行大量重构，而标准 Wine 主干完全没有考虑这种模式。

最后，是 UI 框架。标准 Wine 使用 X11 或 Wayland 作为其 GUI 后端。macOS/iOS 没有 X11。Madeira 必须抛弃所有 X11 相关的代码，完全重写 GUI 子系统，使其直接与 Cocoa（macOS）或 UIKit（iOS）对话。这意味着所有的窗口创建、消息循环、绘图、事件分发，都必须用 Objective-C/Swift 重写。这也是为什么 Madeira 不能被视为 Wine 的一个“分支”，而是一个基于 Wine 核心思想、但几乎全部重写的全新项目。它继承了 Wine 的 DLL 加载器、PE 文件解析器、NT 系统调用模拟器等核心能力，但丢弃了所有与 Unix/Linux 传统环境绑定过深的模块。

2.3 Madeira 的核心价值定位：填补市场空白的务实选择

在当前的技术生态中，Madeira 的定位非常清晰：它不是要取代 Parallels Desktop 或 VMware Fusion，也不是要挑战 Apple 的原生开发战略，而是要精准地解决一个“长尾需求”。这个需求的用户画像很典型：他们有一台性能强大的 M 系列 Mac，但工作中必须依赖某个只有 Windows 版本的、更新缓慢的行业软件；或者他们有一台 iPad Pro，想把它变成一个随身携带的、能运行特定 Windows 工具的生产力终端。对他们来说，Parallels 的成本（每年订阅费）、资源占用（至少 4GB RAM、20GB 磁盘空间）和启动延迟（每次都要启动一个完整的 Windows 系统），都是难以承受的负担。而 Madeira 提供的是一种“轻量化、即开即用”的替代方案。

它的价值体现在三个维度。第一是资源效率。一个典型的 Madeira for macOS App，其自身体积大约在 150MB 左右，运行时内存占用峰值通常在 800MB-1.2GB 之间，远低于虚拟机的 4GB+。这是因为 Madeira 不需要运行一个完整的 Windows 内核，它只是在 macOS 内核之上，用 FEX-Emu 翻译指令，用 DXMT 翻译图形，其余一切（内存管理、磁盘 I/O、网络协议栈）都直接复用 macOS 的原生能力。第二是用户体验。Madeira App 在 macOS 上就是一个标准的 Dock 图标，点击即开，没有虚拟机的“启动画面”和“登录界面”。在 iOS 上，它就是一个全屏 App，可以添加到主屏幕，支持后台音频播放（如果应用本身支持），甚至可以通过 iOS 的“快捷指令”自动化启动。第三是开发友好性。对于开发者而言，Madeira 提供了一套清晰的 SDK 和文档，你可以将自己的 Windows 工具打包成一个.exe，然后通过 Madeira 的命令行工具，一键生成一个 macOS 或 iOS App。这比为每个工具单独开发一个 macOS/iOS 原生版本，成本低了数个数量级。所以，Madeira 的成功，不在于它有多“完美”，而在于它有多“务实”。它承认了 Windows 生态的长期存在，并提供了一条成本最低、阻力最小的共存之路。

3. 核心细节解析：从源码编译到 iOS 签名的全流程详解

3.1 编译环境搭建：macOS 作为唯一可信的构建主机

Madeira 的官方文档明确指出，macOS 是构建 Madeira for iOS 的唯一可信平台。你无法在 Linux 或 Windows 上完成整个流程。原因很简单：Apple 的代码签名工具codesign、应用打包工具xcodebuild、以及最重要的，用于生成 iOS 企业签名证书和 Provisioning Profile 的 Apple Developer Portal，都深度绑定于 macOS 和 Xcode。试图在其他平台上绕过这些，只会陷入无尽的证书错误和签名失败的泥潭。

我的构建主机是一台搭载 M1 Pro 芯片的 MacBook Pro，运行 macOS Sonoma 14.5。这是目前最稳妥的选择，因为新版本的 Xcode（15.3）对 Apple Silicon 的支持最为完善。整个环境搭建的核心，就是确保以下四个组件的版本相互兼容：

1. Xcode: 我安装的是 Xcode 15.3。它自带了最新的 Command Line Tools、iOS SDK（27.2）和 macOS SDK（14.4）。xcode-select --install是第一步，但更重要的是在 Xcode 的 Preferences -> Locations 中，确认 Command Line Tools 的版本与你安装的 Xcode 一致。一个常见的坑是，系统可能残留旧版本的 CLT，导致xcodebuild找不到正确的 SDK。
2. CMake: Madeira 的构建系统基于 CMake。我使用 Homebrew 安装了最新版：brew install cmake。版本必须 >= 3.25，因为较新的 CMake 才能正确识别 Xcode 15 的构建规则。
3. Ninja: 作为 CMake 的后端构建工具，Ninja 比传统的 Make 更快，尤其适合大型项目。brew install ninja。
4. Python 3: 用于运行 Madeira 的构建脚本和一些辅助工具。brew install python3，并确保python3命令在 PATH 中可用。

提示：在开始编译前，务必执行sudo xcodebuild -runFirstLaunch。这是一个隐藏但至关重要的步骤。它会触发 Xcode 的首次初始化，安装所有必需的内部组件（如 Swift 标准库、Clang 编译器插件等）。如果跳过这一步，后续的xcodebuild命令极大概率会报错The requested device could not be found because no devices are connected.，即使你的设备根本没连上——因为 Xcode 的内部环境根本没有准备好。

3.2 源码获取与依赖管理：FEX-Emu 和 DXMT 的 submodule 策略

Madeira 的源码仓库采用 Git Submodule 机制来管理其两大核心依赖：FEX-Emu 和 DXMT。这意味着你不能简单地git cloneMadeira 仓库就完事，还必须递归地拉取所有子模块。

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

这条命令会将 Madeira 主仓库、FEX-Emu 仓库和 DXMT 仓库，都以特定的 commit hash 拉取到本地。这个 hash 是经过 Madeira 团队严格测试的，保证了三者之间的 ABI（应用二进制接口）兼容性。如果你手动更新了 FEX-Emu 或 DXMT 的子模块到最新版，很可能会遇到编译失败或运行时崩溃，因为 Madeira 的胶水层代码是针对那个特定版本的 API 编写的。

依赖管理的难点在于，FEX-Emu 和 DXMT 本身也有复杂的依赖。FEX-Emu 需要 LLVM 作为其 JIT 编译器的后端，而 DXMT 需要 Metal Shader Converter (MSC) 来将 HLSL 着色器转换为 Metal Shading Language (MSL)。幸运的是，Madeira 的构建脚本已经将这些依赖的下载和编译自动化了。你只需要在madeira目录下运行：

./scripts/build.sh --platform ios --arch arm64

这个脚本会依次执行：

• 检查并安装所有必需的构建工具。
• 进入deps/fex-emu目录，使用 CMake + Ninja 编译 FEX-Emu 的静态库libfex.a。
• 进入deps/dxmt目录，同样编译 DXMT 的静态库libdxmt.a。
• 最后，进入src目录，将libfex.a、libdxmt.a以及 Madeira 自身的 Objective-C/Swift 代码，一起链接成一个 iOS Framework。

整个过程耗时很长，通常需要 45 分钟到 1.5 小时，取决于你的 Mac 性能。我建议在开始前，先brew install llvm，这样 FEX-Emu 的编译会快很多，因为它可以直接链接系统已有的 LLVM 库，而不用自己从头编译一份。

3.3 iOS App 的构建与签名：从 .xcworkspace 到 .ipa 文件

当build.sh成功完成后，你会在build/ios-arm64目录下看到一个名为Madeira.xcworkspace的文件。这才是真正的“产品入口”。双击它，会用 Xcode 打开一个完整的 iOS 工程。

这个工程的结构非常清晰：

• Madeiratarget：这是主 App，它包含了所有胶水层代码，负责初始化 FEX-Emu、加载 DXMT、创建主窗口/视图。
• MadeiraCoreframework：这是刚才build.sh生成的静态库，它被嵌入到主 App 中。
• Wineframework：这是 Madeira 对 Wine 核心的精简版封装，只保留了 PE 加载、DLL 导出、NT 系统调用模拟等最核心的功能，去掉了所有 GUI 和 X11 相关代码。

构建和签名的步骤如下：

1. 选择设备与签名团队：在 Xcode 顶部工具栏，将 Build Target 从Any iOS Device (arm64)改为你的物理 iOS 设备（例如iPhone 14 Pro）。然后，在 Project Navigator 中选中Madeira项目，在Signing & Capabilities标签页下，勾选Automatically manage signing，并从Team下拉菜单中选择你的 Apple ID（必须是已加入 Apple Developer Program 的个人或组织账户）。

2. 配置 Bundle Identifier：这是签名的关键。默认的 Bundle ID 是com.madeira.project，但这只是一个占位符。你必须将其修改为一个全局唯一的字符串。我习惯用com.yourname.madeira的格式。一旦你设置了这个 ID，Xcode 就会自动为你在 Apple Developer Portal 上创建一个对应的 App ID 和一个 Development Provisioning Profile。

3. 添加必要权限：为了让 Madeira 能正常工作，你必须在Signing & Capabilities中手动添加几个关键的 Capability：

   • Background Modes: 勾选Audio, AirPlay, and Picture in Picture。这是为了支持后台音频播放，比如运行一个 Windows 音频播放器。
   • Associated Domains: 如果你计划让 Madeira App 通过 Universal Links 打开特定的.exe文件，你需要在这里配置。不过对于初学者，可以先跳过。
   • Keychain Sharing: 勾选此项。Madeira 需要用 Keychain 来安全地存储 Wine 的配置信息和用户密码。

4. 构建与归档：点击 Xcode 工具栏上的Product -> Build，确保编译成功，没有任何错误。然后，点击Product -> Archive。Xcode 会启动一个归档流程，它会将所有代码、资源、框架打包，并进行最终的代码签名。这个过程可能需要几分钟。

5. 导出 .ipa 文件：归档完成后，Xcode 会自动打开Organizer窗口。在Archives标签页下，找到你刚刚创建的归档，点击右侧的Distribute App按钮。在分发向导中，选择Ad Hoc或Enterprise。Ad Hoc适用于最多 100 台设备的测试，你需要提前在 Developer Portal 中注册这些设备的 UDID；Enterprise则适用于企业内部无限设备分发，但需要购买企业开发者账号（99 美元/年）。选择好后，按照向导操作，最终会生成一个.ipa文件。这个文件，就是你可以通过Apple Configurator 2或第三方工具（如Cydia Impactor的继任者）安装到 iOS 设备上的最终产物。

注意：如果你在归档过程中遇到CodeSign error: code signing is required for product type 'Application' in SDK 'iOS'错误，这几乎 100% 是因为你的 Apple ID 没有被正确关联到一个有效的 Developer Team。请退出 Xcode，重新登录 Apple ID，并在Xcode Preferences -> Accounts中，点击你的 Apple ID，然后点击Manage Certificates...，确保里面有一个iOS Development和一个iOS Distribution证书。如果没有，点击左下角的+号来创建。

4. 实操过程与核心环节实现：解决 wine 乱码、通知横幅与浏览器唤起的实战方案

4.1 wine 乱码问题的根源与系统级字体修复

“wine 乱码”是 Madeira 用户反馈最多的问题之一。当你在 Madeira 中启动一个 Windows 应用，菜单栏、按钮文字、甚至整个窗口都显示为方块或问号。这个问题的根源，90% 都出在字体上。Windows 应用默认使用SimSun（宋体）、Microsoft YaHei（微软雅黑）等中文字体。而 Madeira 的 Wine 环境，默认的字体映射表（fonts.conf）是为空的，它不知道该用哪个 macOS/iOS 字体来替代这些 Windows 字体。

解决这个问题，不能靠简单的复制粘贴，而是一套系统性的修复流程。核心思路是：在 Madeira App 的沙盒内，建立一个完整的、可被 Wine 识别的字体目录，并通过修改 Wine 的注册表，强制指定中文字体。

第一步，准备字体文件。你不能直接使用 macOS 系统字体（如PingFang.ttc），因为它们的版权和许可不允许被嵌入到第三方 App 中。你需要寻找开源的、可商用的中文字体。我推荐Noto Sans CJK SC（思源黑体简体中文版），它由 Google 和 Adobe 联合开发，采用 SIL Open Font License，可以自由使用和分发。从 Google Fonts 下载NotoSansCJKsc-Regular.otf和NotoSansCJKsc-Bold.otf。

第二步，将字体文件放入 App 沙盒。在 Xcode 的Madeira项目中，将这两个.otf文件拖入到Madeiratarget 下的Resources文件夹中。确保在弹出的对话框中，勾选Copy items if needed和Add to targets: Madeira。这样，这两个字体文件就会被打包进.ipa文件，并在 App 安装后，位于Bundle Resources目录下。

第三步，编写启动脚本，自动完成字体安装。在Madeira的AppDelegate.m中，application:didFinishLaunchingWithOptions:方法里，添加如下逻辑：

// 获取 Bundle 中的字体路径 NSString *fontRegularPath = [[NSBundle mainBundle] pathForResource:@"NotoSansCJKsc-Regular" ofType:@"otf"]; NSString *fontBoldPath = [[NSBundle mainBundle] pathForResource:@"NotoSansCJKsc-Bold" ofType:@"otf"]; // 获取 App 沙盒内的 Wine 字体目录 NSString *wineFontsDir = [NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES).firstObject stringByAppendingPathComponent:@"Application Support/Madeira/wine/fonts"]; // 创建目录 [[NSFileManager defaultManager] createDirectoryAtPath:wineFontsDir withIntermediateDirectories:YES attributes:nil error:nil]; // 复制字体文件 [[NSFileManager defaultManager] copyItemAtPath:fontRegularPath toPath:[wineFontsDir stringByAppendingPathComponent:@"simsum.ttf"] error:nil]; [[NSFileManager defaultManager] copyItemAtPath:fontBoldPath toPath:[wineFontsDir stringByAppendingPathComponent:@"msyh.ttf"] error:nil];

这段代码会在 App 第一次启动时，将NotoSansCJKsc-Regular.otf复制为simsum.ttf，将NotoSansCJKsc-Bold.otf复制为msyh.ttf，并放入 Wine 的标准字体目录。.ttf是 Wine 识别的扩展名，即使源文件是.otf，我们也必须重命名为.ttf。

第四步，修改 Wine 注册表。Wine 的字体映射规则存储在注册表键HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\FontSubstitutes下。我们需要在 App 启动时，动态地向这个键写入值。Madeira 提供了一个 C APIwine_set_registry_string()，我们可以这样调用：

// 强制将 "SimSun" 映射为 "Noto Sans CJK SC" wine_set_registry_string(HKEY_LOCAL_MACHINE, @"Software\\Microsoft\\Windows NT\\CurrentVersion\\FontSubstitutes", @"SimSun", @"Noto Sans CJK SC"); wine_set_registry_string(HKEY_LOCAL_MACHINE, @"Software\\Microsoft\\Windows NT\\CurrentVersion\\FontSubstitutes", @"Microsoft YaHei", @"Noto Sans CJK SC"); wine_set_registry_string(HKEY_LOCAL_MACHINE, @"Software\\Microsoft\\Windows NT\\CurrentVersion\\FontSubstitutes", @"Arial", @"Helvetica");

完成这四步后，重新编译、归档、安装。你会发现，所有 Windows 应用的中文显示都变得清晰锐利。这个方案的优势在于，它完全在 App 沙盒内完成，不依赖于系统字体，也不违反 Apple 的 App Store 审核指南，因为所有字体文件都是我们自己打包进去的。

4.2 notification banner 仿 iOS 通知横幅：实现原生级的 UI 交互

Madeira 的一个高级功能，是能够从 Windows 应用内部，向 iOS 系统发送通知。例如，当一个 Windows 下载工具完成下载时，它应该能在 iOS 屏幕顶部弹出一个标准的通知横幅（Notification Banner），而不是在 App 内部弹出一个丑陋的 MessageBox。这极大地提升了用户体验的“原生感”。

实现这个功能，需要跨越两个世界：Windows 的 Win32 API 和 iOS 的 UserNotifications 框架。Madeira 的胶水层为此提供了一个精巧的桥接机制。

在 Windows 应用端，你需要调用一个特殊的、Madeira 提供的自定义 DLL 函数。这个 DLL 名为madeira_notify.dll，它会被自动注入到每一个由 Madeira 启动的 Windows 进程中。它的导出函数非常简单：

// C++ 声明 extern "C" { __declspec(dllexport) void Notify(const char* title, const char* body, const char* soundName); }

在你的 Windows C++ 代码中，你可以这样调用它：

typedef void (*NotifyFunc)(const char*, const char*, const char*); HMODULE hMod = LoadLibraryA("madeira_notify.dll"); if (hMod) { NotifyFunc pfnNotify = (NotifyFunc)GetProcAddress(hMod, "Notify"); if (pfnNotify) { pfnNotify("下载完成", "文件 test.zip 已保存到 Downloads 目录", "default"); } FreeLibrary(hMod); }

在 Madeira 的 iOS 端，madeira_notify.dll的实现，本质上是一个对UserNotifications框架的 Objective-C 封装。当Notify()函数被调用时，它会通过一个预定义的 IPC（进程间通信）通道，将title、body、soundName这三个字符串，发送给主 App 进程。主 App 进程收到后，会执行以下 Objective-C 代码：

// 创建通知内容 UNMutableNotificationContent *content = [[UNMutableNotificationContent alloc] init]; content.title = [NSString stringWithUTF8String:title]; content.body = [NSString stringWithUTF8String:body]; content.sound = [UNNotificationSound soundNamed:[NSString stringWithUTF8String:soundName]]; // 创建通知请求 UNNotificationRequest *request = [UNNotificationRequest requestWithIdentifier:@"madeira_notification" content:content trigger:nil]; // 添加到通知中心 [[UNUserNotificationCenter currentNotificationCenter] addNotificationRequest:request withCompletionHandler:^(NSError * _Nullable error) { if (error) { NSLog(@"通知发送失败: %@", error); } }];

这个方案的精妙之处在于，它完全遵循了 iOS 的通知最佳实践。通知会出现在锁屏、通知中心，并且支持声音、震动等所有原生特性。用户点击通知，会直接回到 Madeira App，并可以继续操作。这比在 App 内部画一个假的横幅要专业得多，也更符合用户的直觉。

4.3 iOS 浏览器唤起安装 App：Universal Links 与自定义 URL Scheme 的双保险策略

“ios浏览器唤起安装app”是 Madeira 分发流程中至关重要的一环。想象一下，用户在 Safari 里访问你的网站，点击一个“立即安装”按钮，就能直接跳转到 Madeira App 的安装页面，而不是下载一个.ipa文件再手动安装。这需要一套可靠的 URL 唤起机制。

Madeira 同时支持两种机制：自定义 URL Scheme和Universal Links，并推荐采用“双保险”策略，以覆盖所有 iOS 版本和所有可能的网络环境。

自定义 URL Scheme是最简单、兼容性最好的方案。你只需要在 Xcode 的Info.plist文件中，添加一个新的CFBundleURLTypes数组项：

<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleTypeRole</key> <string>Editor</string> <key>CFBundleURLName</key> <string>com.yourname.madeira</string> <key>CFBundleURLSchemes</key> <array> <string>madeira</string> </array> </dict> </array>

这表示，你的 App 声明了对madeira://这个 URL Scheme 的所有权。然后，在你的网页上，放置一个按钮，其onclick事件为：

<a href="madeira://install?app=notepad">安装记事本</a>

当用户点击这个链接时，Safari 会检测到madeira://Scheme，并询问用户是否要打开 Madeira App。如果 App 已安装，就会被唤起；如果未安装，Safari 会报错。这个方案的缺点是，它无法区分“App 已安装”和“App 未安装”的情况，用户体验不够优雅。

Universal Links则是苹果官方推荐的、更现代的方案。它利用 HTTPS 网站和 App 之间的信任关系，实现无缝跳转。要启用它，你需要做两件事：

1. 在你的网站上托管apple-app-site-association文件。这是一个没有文件扩展名的 JSON 文件，必须放在你网站的根目录（https://yourdomain.com/apple-app-site-association），并且必须通过 HTTPS 访问。文件内容如下：

{ "applinks": { "apps": [], "details": [ { "appID": "TEAMID.com.yourname.madeira", "paths": ["/install/*", "/app/*"] } ] } }

其中TEAMID是你在 Apple Developer Portal 中看到的 10 位字母数字组合（例如ABCD123456）。paths数组定义了哪些网站路径可以被关联到你的 App。

2. 在 Xcode 中启用 Associated Domains Capability。在Signing & Capabilities标签页，点击+ Capability，添加Associated Domains。然后在下方的 Domains 列表中，添加一行：applinks:yourdomain.com。

完成这两步后，当用户在 Safari 中访问https://yourdomain.com/install/notepad时，Safari 会自动验证apple-app-site-association文件，并在地址栏左侧显示一个“打开”图标。点击它，如果 App 已安装，会直接打开；如果未安装，则会跳转到你网站上预设的下载页面。这个流程完全静默、无感知，是目前最完美的唤起方案。

实操心得：我强烈建议你同时启用这两种方案。在网页上，先尝试 Universal Links，如果检测到失败（例如用户使用的是旧版 iOS），则优雅降级到自定义 URL Scheme。你可以用 JavaScript 检测navigator.userAgent来判断 iOS 版本，并用setTimeout来监控window.location是否发生了跳转，以此来判断唤起是否成功。这是一个成熟的、已被无数 App 验证过的最佳实践。

5. 常见问题与排查技巧实录：从构建失败到运行崩溃的终极排障指南

5.1 构建阶段常见错误与解决方案

构建阶段的错误，往往是最令人沮丧的，因为它们发生在你还没看到任何运行效果之前。根据我过去三个月的记录，以下是出现频率最高的五个错误及其解决方案。

错误1：CMake Error at CMakeLists.txt:123 (find_package): By not providing "FindFEX.cmake" in CMAKE_MODULE_PATH this project has asked CMake to find a package configuration file provided by "FEX"

这个错误表明 CMake 找不到 FEX-Emu 的构建产物。根本原因通常是build.sh脚本在编译 FEX-Emu 时失败了，但脚本本身没有抛出错误，导致后续步骤继续执行。解决方案是，不要直接运行build.sh，而是分步执行，逐一检查每个依赖的编译日志。

# 进入 FEX-Emu 目录，手动构建 cd deps/fex-emu mkdir build && cd build cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DFEX_ARCH=ARM64 .. ninja

如果ninja命令报错，仔细阅读错误信息。最常见的原因是缺少 LLVM。此时，运行brew install llvm，然后重新执行