第二章：环境搭建：从 WinUI 到 WebAssembly

# 第二章：环境搭建：从 WinUI 到 WebAssembly > **本章导读**：在这一章，我们将完成一个看似枯燥但至关重要的任务——搭建开发环境。你可能会想："这不就是点点安装按钮吗？"但跨平台开发的环境配置就像是在建造一座精密仪器的实验室——每一个组件都必须精确安装，否则后续的实验就无法进行。让我们像费曼组装物理实验设备一样，一丝不苟地完成这个基础建设。 --- ## 🏗️ 2.1 理解跨平台环境的复杂性 在开始安装软件之前，让我们先理解为什么 Uno Platform 的环境配置比传统开发更复杂。这就像理解为什么建造一座桥梁需要的准备工作比建造一间木屋更多——不是因为桥梁本身更复杂，而是因为它要跨越更复杂的地形。 ### 🌐 2.1.1 多个世界的交汇点 当你使用 Uno Platform 开发应用时，你实际上是在同时与多个技术世界打交道。 Windows 世界需要 WinUI 3 和 Windows App SDK，它们依赖特定的 Windows 版本和运行时。iOS 世界需要 Xcode 的命令行工具、Apple 的 SDK，以及一台 Mac 来进行最终编译（即使你的主要开发机是 Windows）。Android 世界需要 Android SDK、Java JDK，以及一系列构建工具。Web 世界则需要 .NET 的 WebAssembly 编译器和浏览器兼容性工具链。 > **第一性原理**：为什么需要这么多组件？因为 Uno 的"魔法"本质上是在编译时将你的统一代码翻译成各平台的本地代码。这个翻译过程需要各平台的"词典"——也就是 SDK。没有这些词典，翻译就无法进行。 ### 💻 2.1.2 硬件选择的战略考量 选择开发 Uno 应用的硬件，就像选择一辆要穿越多种地形的车——你需要考虑它要面对的所有路况。 **Windows 11** 是开发 Uno 应用的首选平台，这不是偏见，而是技术必然。WinUI 3 —— Uno 的核心 API 来源——在 Windows 11 上有最好的支持。更重要的是，Visual Studio 2022 的完整功能只在 Windows 上可用，包括强大的 XAML 热重载、可视化设计器和深度调试工具。 > **那 macOS 用户怎么办？** 如果你主要使用 Mac，不必担心。你可以使用 Visual Studio Code 配合 C# Dev Kit 进行大部分开发工作，或者使用 JetBrains Rider 这个跨平台的 IDE。但对于 iOS 应用的最终编译，你无论如何都需要一台 Mac（可以是 Mac mini 这样相对便宜的设备）。许多团队采用"Windows 主力开发 + Mac 远程编译"的混合模式。 内存是另一个需要认真考虑的资源。跨平台开发涉及多个 SDK 同时运行、Android 模拟器占用大量 RAM、以及 WebAssembly 编译时的内存开销。**16GB 是起点，32GB 更为舒适**。想象一下你的电脑是一个工作台——如果工作台太拥挤，你就需要频繁地把工具放回架子再取出来，这会严重拖慢工作节奏。 ## 📦 2.2 Visual Studio 2022：开发的核心枢纽 虽然轻量级的代码编辑器如 VS Code 也能进行 Uno 开发，但 Visual Studio 2022 提供了最完整的开发体验。让我们像拆解一台精密机器一样，看看如何正确安装和配置它。 ### 🔧 2.2.1 工作负载的选择艺术 Visual Studio 的安装程序是一个功能强大的包管理器，但它的选项之多常常让人眼花缭乱。理解每个工作负载的作用，能帮助你做出明智的选择。 **.NET 桌面开发**是基础中的基础。它包含了 .NET SDK、C# 编译器、以及开发桌面应用所需的基本工具。即使你只打算开发移动应用，这个工作负载也是必需的，因为 Uno 的共享代码库本质上是一个 .NET 项目。 **使用 .NET 的移动开发**（原 Xamarin 工作负载）为你打开了移动世界的大门。它包含 Android SDK 的管理器、iOS 的远程编译工具链、以及各种移动设备模拟器。请注意，这个工作负载的安装时间可能较长，因为它需要下载大量的 SDK 和工具链。 > **什么是 SDK？** SDK（Software Development Kit，软件开发工具包）是一组工具的集合，它让你能够为特定平台开发应用。想象 SDK 是一个翻译官的工具箱——里面有所需的词典、语法书和速查表。Android SDK 让你的电脑"学会"Android 的语言，iOS SDK 则让它"学会"iOS 的语言。 **通用 Windows 平台开发**虽然在名字上似乎与 WinUI 3 无关，但实际上包含了一些关键的构建工具。特别是对于使用旧版 Uno 模板的项目，这个工作负载仍然是必需的。即使你的目标是最新的 WinUI 3，保留这个工作负载也不会有什么坏处。 **ASP.NET 和 Web 开发**看起来似乎与客户端开发无关，但对于 WebAssembly 开发却是必不可少的。Uno 的 WASM 项目使用 ASP.NET Core 作为托管服务器，用于开发时的热重载和生产时的静态文件服务。 ### ⚙️ 2.2.2 单个组件的精细调整 在"单个组件"选项卡中，有一个特别重要的组件值得单独关注：**.NET WebAssembly 构建工具**。 这个组件是将 C# 代码编译成浏览器可执行格式的关键。没有它，你的 WASM 项目将无法编译。安装它会同时安装一些辅助工具，如 wasm-opt（WebAssembly 优化器）和相关的诊断工具。 > **WebAssembly 是如何工作的？** 传统上，浏览器只能运行 JavaScript。WebAssembly 引入了一种新的二进制格式，可以被浏览器高效执行。你的 C# 代码首先被编译成 .NET 中间语言（IL），然后由 WASM 构建工具转换成 WebAssembly 二进制格式。在运行时，一个精简版的 .NET 运行时会在浏览器中加载，执行你的代码。这就是为什么 Uno 应用能在浏览器中运行——浏览器实际上是在运行一个小型的 .NET 环境。 ## 🛠️ 2.3 Uno Check：环境的智能诊断师 安装了 Visual Studio 之后，你可能会想："现在可以开始写代码了吗？"先别急，让我们先确保所有组件都正确配置。这就是 `uno-check` 工具大显身手的时候。 ### 🔍 2.3.1 为什么需要 uno-check？ 跨平台开发环境涉及数十个组件，每个组件都有其特定的版本要求。Java JDK 需要 11 或 17 版本，Android SDK 需要特定的 API 级别，Xcode 需要与你的 macOS 版本兼容... 这些依赖关系形成了一个复杂的网，手动检查每一个节点几乎是不可能的。 `uno-check` 就像一个经验丰富的机械师，它会自动检测所有关键组件的状态，并给出明确的修复建议。这大大降低了"我的代码没问题但就是跑不起来"这类问题的发生概率。 ### 💻 2.3.2 运行 uno-check 打开 PowerShell（以管理员身份运行更佳），执行以下命令： ```powershell # 安装 uno-check 工具 dotnet tool install -g uno.check # 运行诊断 uno-check ``` 工具启动后，你会看到一个彩色的检查清单。绿色的勾表示一切正常，黄色的警告表示可选的优化，而红色的叉则需要立即处理。 常见的需要修复的问题包括：Android SDK 许可协议未接受（只需运行 `android-sdk-license` 接受脚本）、缺少特定的 Android API 级别（通过 Android SDK Manager 安装）、或者 Java 环境变量未正确配置。 > **第一性原理思考**：为什么有这么多"许可协议"需要接受？因为这些 SDK 大多由各平台厂商提供，它们希望你明确知道自己在使用它们的工具。这就像借用别人的工具前需要打个招呼——是行业惯例，也是法律要求。 ## 📋 2.4 项目模板：快速启动的秘密武器 环境配置完成后，下一步是创建项目。手动配置一个支持多平台的 Uno 项目是可能的，但这涉及到创建多个项目文件、配置复杂的引用关系、设置条件编译符号... 这个过程可能耗费数小时，而且极易出错。 ### 🎯 2.4.1 安装官方模板 Uno 团队提供了完善的 dotnet 模板，让你可以在几分钟内创建一个配置完整的项目。安装命令非常简单： ```powershell dotnet new install Uno.Templates ``` 这个命令会安装多种模板，包括标准的应用模板、类库模板、以及针对特定场景（如 MAUI 嵌入、Skia 渲染）的特殊模板。 ### 🏗️ 2.4.2 创建你的第一个项目 安装模板后，你有两种创建项目的方式：使用命令行或使用 Visual Studio 的图形界面。 使用命令行的方式更加灵活，适合自动化场景： ```powershell # 创建一个基础 Uno 项目 dotnet new unoapp -o MyFirstUnoApp # 创建一个使用 MVUX 模式的高级项目 dotnet new unoapp -o MyAdvancedApp -preset recommended ``` 使用 Visual Studio 的方式则更加直观。在"创建新项目"对话框中搜索"Uno"，你会看到多个选项。选择 **Uno Platform App**，然后点击下一步。 在配置页面，你会面对多个选择，让我们逐一理解它们的含义。 **平台选择**决定了你的项目将支持哪些目标。对于初学者，建议至少选择 Windows、WASM 和 Android。iOS 的支持需要 Mac 环境，如果你暂时没有，可以先跳过。 > **多目标 vs 多项目**：Uno 支持两种项目结构。多项目结构为每个平台创建独立的项目文件（MyApp.Windows.csproj、MyApp.Android.csproj 等），这种方式更容易理解和调试。多目标结构则使用单个项目文件，通过条件编译来区分平台，这种方式更简洁但调试更复杂。初学者建议从多项目结构开始。 **表现层模式**决定了你如何组织 UI 代码。MVVM 是经典的模式，几乎所有 .NET 开发者都熟悉它。MVUX 是 Uno 特有的创新，它在处理异步数据流时更加优雅，但学习曲线稍陡。建议初学者从 MVVM 开始，在熟悉 Uno 后再尝试 MVUX。 **主题选择**影响应用的默认外观。Fluent 是 Windows 的设计语言，也是 Uno 的默认选择。如果你希望应用在移动端看起来更原生，可以选择 Material（Android 风格）或 Cupertino（iOS 风格）。 ## 🚀 2.5 验证环境：让应用跑起来 创建项目后，最重要的一步是验证环境配置正确。让我们依次在不同的平台上运行你的 Hello World 应用。 ### 🪟 2.5.1 运行 Windows 版本 这是最简单的验证步骤。在 Visual Studio 的解决方案资源管理器中，右键点击以 `.Windows` 结尾的项目，选择"设为启动项目"。然后按 F5 或点击绿色的"启动"按钮。 如果一切正常，你会看到一个窗口弹出，显示"Hello, World!"（或你选择的默认内容）。这个窗口使用的是真正的 WinUI 3 控件，和 Windows 11 系统应用使用相同的技术栈。 > **为什么先测试 Windows？** 因为 Windows 是开发环境本身运行的系统，所以它涉及的外部依赖最少。如果 Windows 版本都跑不起来，说明基础环境就有问题，需要先修复再继续。 ### 🌐 2.5.2 运行 WebAssembly 版本 WASM 版本是最令人兴奋的——你的 C# 代码将在浏览器中运行！选择以 `.Wasm` 结尾的项目作为启动项目，然后启动调试。 首次运行 WASM 项目时，你可能需要等待较长时间。这是因为 .NET 运行时需要被下载和初始化。你会在浏览器窗口的底部看到一个加载进度条。 > **首次加载为什么这么慢？** 浏览器需要下载整个 .NET 运行时（大约 2-5MB）和你的应用代码。这就像下载一个小型的操作系统。好消息是，后续访问会使用浏览器缓存，加载速度会大大提升。在生产环境中，你还可以使用 AOT（Ahead-of-Time）编译和裁剪技术来进一步减小包体积。 如果一切正常，你会看到相同的 Hello World 界面在浏览器中呈现。打开浏览器的开发者工具（F12），切换到 Console 标签，你会看到 .NET 运行时的初始化日志——这是你的 C# 代码在浏览器中活着的证据。 ### 🤖 2.5.3 运行 Android 版本 Android 版本需要一个模拟器或真机。如果你在运行 `uno-check` 时已经安装了模拟器，现在可以直接使用。 首先，在 Visual Studio 中启动 Android Device Manager，确保至少有一个模拟器在运行。然后选择以 `.Android` 结尾的项目作为启动项目。在工具栏的设备下拉列表中，你应该能看到正在运行的模拟器。 点击启动后，Visual Studio 会将应用打包成 APK，部署到模拟器，然后启动它。这个过程可能需要一到两分钟，特别是在首次部署时。 > **部署失败怎么办？** 最常见的原因是 SDK 版本不匹配。检查你的项目的 `TargetFramework` 和 `SupportedOSPlatformVersion` 设置，确保它们与你安装的 Android SDK 版本兼容。另一个常见问题是模拟器性能不足——尝试给模拟器分配更多内存，或者使用 x86_64 系统镜像而不是 ARM 镜像。 ### 🍎 2.5.4 运行 iOS 版本（需要 Mac） iOS 版本的编译必须在 macOS 上进行。如果你有一台 Mac，可以使用 Visual Studio 的"与 Mac 配对"功能，将 Windows 上的项目远程编译到 Mac 上。 首先，在 Mac 上安装 Visual Studio 2022 for Mac 或 Xcode。确保两台电脑在同一网络上。然后在 Windows 的 Visual Studio 中，选择"工具 > iOS > 与 Mac 配对"。 配对成功后，选择以 `.iOS` 结尾的项目作为启动项目。Visual Studio 会将代码发送到 Mac 进行编译，然后将结果部署到 iOS 模拟器或真机。 > **为什么 iOS 必须用 Mac？** 这是 Apple 的政策，不是技术限制。Apple 要求所有 iOS 应用必须使用其官方工具链（Xcode）进行签名和打包。这就是为什么即使你的代码是纯 C#，也需要一台 Mac 来完成最后的编译步骤。 ## 📝 2.6 VS Code：轻量级的替代方案 虽然 Visual Studio 2022 提供了最完整的开发体验，但它的体积和资源消耗也不小。如果你偏好轻量级工具，或者使用 macOS/Linux，VS Code 是一个很好的替代选择。 ### 🔌 2.6.1 必装扩展 在 VS Code 中进行 Uno 开发，需要安装以下扩展： **C# Dev Kit** 是微软官方的 C# 开发扩展包，提供了代码补全、调试、测试运行等功能。它本质上是将 Visual Studio 的核心能力移植到了 VS Code。 **Uno Platform 扩展** 是 Uno 团队提供的专用工具，包括 XAML 语法高亮、智能提示和预览功能。安装后，你可以通过命令面板（Ctrl+Shift+P）运行 `Uno: Open XAML Previewer` 来实时预览界面。 ### 🎨 2.6.2 预览器的使用 VS Code 中的 XAML 预览器虽然不如 Visual Studio 的设计器强大，但对于快速验证布局已经足够。打开一个 XAML 文件，然后运行预览命令。预览窗口会显示在编辑器旁边，你可以在代码中修改属性，预览会实时更新。 > **预览器的局限性**：VS Code 的预览器使用的是简化的渲染引擎，可能无法完美显示某些复杂控件或自定义渲染器。对于精确的 UI 调试，仍然建议使用 Visual Studio 的完整设计器。 ## 🔧 2.7 常见问题与解决方案 即使按照上述步骤操作，你也可能遇到一些问题。让我们预先准备一些解决方案。 ### 🐛 2.7.1 "无法找到 .NET SDK" 这个问题通常是因为 PATH 环境变量没有正确配置。在命令行中运行 `dotnet --list-sdks`，确认 SDK 已经安装。如果列表为空，需要重新安装 .NET SDK 或手动添加路径到 PATH。 ### 🐛 2.7.2 "Android SDK 路径未找到" Visual Studio 通常会自动管理 Android SDK 的路径，但有时需要手动指定。在 Visual Studio 中，打开"工具 > 选项 > Xamarin > Android 设置"，检查"Android SDK 位置"是否正确。 ### 🐛 2.7.3 "WASM 项目启动失败" 最常见的原因是端口冲突。WASM 项目默认使用 IIS Express 作为本地服务器，如果默认端口被占用，启动就会失败。解决方法是编辑 `.Wasm` 项目的 `launchSettings.json`，更改端口号。 ## 📚 本章小结 环境搭建是跨平台开发的第一道门槛，也是最容易被忽视的环节。一个配置正确的开发环境，就像一辆加满油、调试完毕的赛车——它不能保证你赢得比赛，但至少不会因为机械故障而让你半途退赛。 在本章中，我们安装了 Visual Studio 2022 和相关的工作负载，运行了 `uno-check` 进行环境诊断，创建了第一个 Uno 项目，并在多个平台上成功运行了它。这些步骤看似繁琐，但它们为你接下来的学习之旅奠定了坚实的基础。 在下一章，我们将深入解剖 Uno 项目的内部结构，看看那些自动生成的文件背后隐藏着什么秘密。当你理解了项目是如何组织的，你就能够更自信地构建复杂的应用。 --- > **动手实验**： > 1. 尝试在 Visual Studio 中创建一个使用 MVUX 模式而不是 MVVM 模式的项目，观察生成的文件结构有什么不同。 > 2. 使用 `uno-check --fix` 命令，让工具自动修复检测到的问题，观察它做了哪些修改。 > 3. 在 WASM 项目运行时，打开浏览器开发者工具，查看 Network 标签，了解应用加载了哪些文件，它们的体积各是多少。