让您的 .NET MAUI 应用为 Xcode 27 做好准备

如果现有 .NET MAUI 应用能够使用 Xcode 27 构建、安装到运行 iOS 27 的 iPhone 上，却只显示启动画面便退出，首先应检查 UIScene 生命周期适配。根据微软 2026 年 10 月 19 日发布的指导，这种现象可能由多种因素造成；但如果环境中唯一的变化是 Xcode 和 iOS 版本，并且设备日志明确提示必须采用 UIScene，那么所需工作通常比较明确。

Xcode 27 改变了什么

UIScene 负责管理应用的界面实例、窗口以及前台和后台状态之间的转换，并与管理整个应用进程的应用生命周期协同工作。微软指出，这不是 .NET MAUI 生命周期机制失效，而是使用 Xcode 27 构建时新增的兼容性要求。该模型自 iOS 13 起就已存在，.NET MAUI 也已经提供相应支持。

更新 .NET MAUI 包或工作负载并不会自动重写现有项目的 iOS 平台文件，因此旧项目可能仍只使用原来的应用生命周期。微软说明，这一要求适用于使用 Xcode 27 构建的所有形态 iOS 应用，与特定设备无关；使用旧 SDK 构建并已安装的二进制文件，也不会仅仅因为手机升级到 iOS 27 就突然需要迁移。

使用微软的迁移技能

对包含认证回调、深层链接、通知跳转或 App Actions 的项目，微软提供了一个实验性的 maui-xcode27-migration 智能代理技能。它会引导代理检查项目、执行迁移并验证结果，但不会取代开发人员的代码审查。该技能及其 .NET MAUI CLI 目前属于预览功能，不在 Microsoft Support Policy 覆盖范围内。

技能要求 Microsoft.Maui.Cli 0.1.0-preview.13.26512.5 或更高版本：

dotnet tool install --global Microsoft.Maui.Cli --version 0.1.0-preview.13.26512.5

dotnet tool update --global Microsoft.Maui.Cli --version 0.1.0-preview.13.26512.5

随后在应用仓库中检查并安装技能：

maui ai list
maui ai add skill maui-xcode27-migration --env CopilotCli --yes

如果使用其他 AI 提供商，应通过 maui ai add skill --help 确认相应的环境参数。安装完成后，重启或重新加载代理会话，并要求它先检查项目和工具链，保留自定义生命周期行为，验证迁移，并在更改 SDK 或放弃旧操作系统支持前征求确认。

这一流程没有 maui migrate 命令；安装技能本身也不会修改应用。如果更喜欢直接管理 GitHub Copilot CLI 插件，也可以添加 dotnet/maui-labs marketplace，再安装 dotnet-maui@dotnet-maui-labs。两种方式选择一种即可，避免安装重复副本。

迁移前需要检查的内容

微软的技能会识别实际使用的项目文件、.NET SDK、.NET MAUI 包、Apple 工作负载和 Xcode 版本，因为 global.json、共享版本配置或已有自定义场景代理都可能改变迁移方案。检查范围还包括：

使 Apple 工作负载与 Xcode 匹配，并确认最低部署目标；
统一 iOS 和 Mac Catalyst 的场景委托与清单，包括不同构建配置使用的 plist；
保留现有启动画面、多窗口和自定义场景行为；
审查认证、冷启动与热启动链接、通知跳转及 App Actions；
执行只读生命周期审计、构建受影响目标并报告未能验证的项目。

可先运行 maui doctor，检查当前 .NET SDK、MAUI 工作负载、Xcode、Apple SDK、许可证及已安装的模拟运行时。对于 .NET 10 项目，微软建议在启用场景前将 .NET MAUI 包更新到 10.0.110 或更高版本。该版本包含场景侧的 App Actions 分发和 WebAuthenticator 回调转发；只添加两个文件虽然也可能解决启动问题，却可能遗漏这些集成行为。

手工添加场景支持

如果项目已经包含 MauiUISceneDelegate 和匹配的场景清单，可以跳过本节，但仍需检查工具链并在 iOS 27 上测试。默认 iOS 场景代理位于 Platforms/iOS/SceneDelegate.cs：

using Foundation;
using Microsoft.Maui;

namespace MyMauiApp;

[Register("SceneDelegate")]
public class SceneDelegate : MauiUISceneDelegate
{
}

将命名空间替换为应用自己的命名空间。若已有注册过的场景代理，应保留其行为并统一注册名称，而不是再添加一个竞争性的代理。原有的 AppDelegate : MauiUIApplicationDelegate 也应继续保留，两者协同工作。

接着在 Platforms/iOS/Info.plist 的根字典中加入：

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>__MAUI_DEFAULT_SCENE_CONFIGURATION__</string>
                <key>UISceneDelegateClassName</key>
                <string>SceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

必须保留 __MAUI_DEFAULT_SCENE_CONFIGURATION__，并让清单中的代理名称与 C# 注册名称一致。除非应用确实支持多窗口，否则应保持 UIApplicationSupportsMultipleScenes 为 false。.NET MAUI 通过代码创建窗口，不需要 UISceneStoryboardFile，现有启动画面配置也不应删除。

Debug、Release、客户版或环境构建可能使用不同 plist，所有可能生成交付包的清单都需要同步修改。若应用使用自定义配置名称，或重写了 GetConfiguration、WillConnect，应联合审查这些实现，不能直接用默认清单覆盖。目标包含 Mac Catalyst 时，还需在对应目录添加场景代理和清单配置。

最低系统版本与自定义生命周期

截至上述资料日期，.NET 10 的 iOS 和 Mac Catalyst 工作负载 27.0.10722 要求 Xcode 27.0。升级 Xcode 并不会自动让现有工作负载兼容，应使用对应版本，而不是关闭 SDK 的 Xcode 检查。

新的 .NET for iOS 和 .NET for Mac Catalyst 27 SDK 分别要求 iOS 15.0 和 Mac Catalyst 17.0（macOS 14 Sonoma）。如果项目仍需支持更旧系统，应暂时使用兼容的 26.x SDK，并单独决定支持策略；也可在 .csproj 的现有 PropertyGroup 中提高 SupportedOSPlatformVersion，但不要添加会覆盖原值的重复项。

启用场景后，UIKit 不再把激活、后台化、URL 和用户活动回调发送给 AppDelegate。原有的 ConfigureLifecycleEvents 注册以及 OpenUrl、ContinueUserActivity 等重写，应迁移到对应的 SceneOnActivated、SceneDidEnterBackground、SceneOpenUrl 和 SceneContinueUserActivity 等场景事件。两类回调参数不同，因此不能只改注册名称。

冷启动链接和用户活动会通过 SceneWillConnect 的 UISceneConnectionOptions 到达，但此时 MAUI 尚未创建窗口，导航应延后到窗口可用之后。通知跳转信息位于 ConnectionOptions.NotificationResponse。普通启动可能没有 URL 或用户活动，处理前必须检查其是否存在。

FinishedLaunching 仍会执行，但标准场景路径会在之后创建窗口，因此 AppDelegate.Window 可能为 null。自定义场景代理重写方法时必须调用基类实现，否则可能影响窗口创建、生命周期事件和认证转发。App Actions 的完成回调必须且只能调用一次：已处理时传入 true，未处理时传入 false。异步处理器可以稍后完成确认，但仅返回处理器并不等于确认操作。

构建与验证

完成修改后先保存当前工作并审查差异，再构建 iOS 目标：

dotnet restore -p:TargetFramework=net10.0-ios
dotnet build -f net10.0-ios --no-restore

如果模拟器中仍运行旧版本，可卸载应用、删除项目的 bin 和 obj 目录后重新执行。还应分别测试 Debug 和 Release 构建，并覆盖冷启动、前后台切换、认证流程、应用运行和完全关闭状态下的链接与通知跳转，以及 App Actions。iOS 26 上能够启动并不能证明使用 Xcode 27 构建的应用可在 iOS 27 正常运行；目标包含 Mac Catalyst 时，也必须单独构建并验证该目标。

资料来源：Get Your .NET MAUI App Ready for Xcode 27（2026-10-19）。