WinUI 3 项目环境搭建与 Packaged / Unpackaged 选型指南（winui-app Skill 实战）

WinUI 3 项目环境搭建与 Packaged / Unpackaged 选型指南（winui-app Skill 实战）

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本文以 winui-app Skill 中的核心参考文档 foundation-setup-and-project-selection.md 为主体，结合其捆绑的 SKILL.md 工作流与 config.yaml 引导配置，系统讲解从零开始准备 WinUI 3 开发机器、选择项目模板与打包模型（packaged / unpackaged）、完成首次脚手架搭建的完整路径。读者读完本文后，将掌握：机器基线检查与一键修复的方法、C# WinUI 3 项目的默认选型决策、packaged 与 unpackaged 两种打包模型的适用场景与取舍，以及如何用dotnet new winui脚手架启动一个可验证运行的首个项目。

1. 本文档的定位：什么时候需要它

foundation-setup-and-project-selection.md是 winui-app Skill 中优先级为 CRITICAL 的基础参考文件之一。它专门服务于以下三类场景：

• 用户从零开始启动一个 WinUI 项目；
• 用户需要选择项目模板；
• 用户询问"一台机器在开始写 WinUI 代码之前需要准备什么"。

它与同目录下的 foundation-environment-audit-and-remediation.md（机器就绪审计与修复）、foundation-template-first-recovery.md（模板优先的故障恢复）构成完整的"基础（Foundations）"四件套，分别回答"该不该做、机器行不行、怎么做、坏了怎么救"四个问题。本文聚焦第一个问题——环境搭建与项目选择。

2. 核心原则：Prefer 与 Avoid

该参考文档以一组精炼的工程原则开篇，这些原则贯穿整个 skill 的所有操作流程。

2.1 应当优先（Prefer）

• 统一走 setup-and-scaffold 流程：前置条件安装、模板校验和首次脚手架搭建，一律使用 SKILL.md 中定义的 setup-and-scaffold 流程，而不是东拼西凑手动安装步骤。
• C# 优先：除非用户有明确理由选择 C++ 或既有的非 WinUI 技术栈，否则默认采用基于 Windows App SDK 的 C# WinUI 3 桌面应用。
• 官方模板与默认打包选择优先：优先使用官方项目模板与默认打包选项。
• 使用受支持的 LTS .NET SDK：对新的 C# 项目，优先使用当前受支持的 LTS .NET SDK，而不是仅仅满足最低版本要求。
• 默认打包（packaged）应用：packaged 应用能获得最顺畅的首个项目体验、最简部署路径，并且天然兼容 Microsoft Store 分发。
• 按需选择非打包（unpackaged）应用：仅当用户明确需要可重复的 CLI 构建-运行验证，或直接启动可执行文件作为常规本地工作流时，才选择 unpackaged。

2.2 应当避免（Avoid）

• 在 skill 的 setup-and-scaffold 流程完成之前就急着开始项目搭建；
• 一上来就选择 unpackaged 部署，除非用户确实需要可重复的 CLI 启动、安装程序、既有桌面应用集成或深思熟虑的运行时策略；
• 在没有验证的情况下给出"机器就绪"的建议——不能把旧的 Windows 构建版本、缺失的 SDK 或残缺的 Visual Studio 安装当作"大概没问题"；
• 把打包模型的选择推迟到启动、存储和启动代码都写完以后——打包模型是地基决策，必须前置。

一句话概括：先验证环境，再选模板，再定打包模型，最后才写代码。

3. 机器就绪基线（Setup Baseline）

参考文档给出了四条硬性基线，它们是评估任何 WinUI 开发机器的最低门槛：

此外还有一条经常被忽略但影响本地调试的关键项：开发者模式（Developer Mode）对常见的本地部署与调试流程很重要。

这些基线并非凭空约定——捆绑的 config.yaml 中，第一段配置即为OS 版本断言：

properties: assertions: - resource: Microsoft.Windows.Developer/OsVersion directives: description: Verify min OS version requirement allowPrerelease: true settings: MinVersion: '10.0.17763'

可以看到MinVersion: '10.0.17763'与文档中的"Windows 10 版本 1809（build 17763）"完全对应，说明这条基线是可被工具自动断言验证的，而非口头约定。

3.1 基线的自动化落地：config.yaml 做了什么

config.yaml 是 skill 捆绑的 WinGet 引导（bootstrap）来源，它一次性完成三件事：

1. 启用开发者模式——通过Microsoft.Windows.Settings/WindowsSettings资源将DeveloperMode设为true（需要 elevated 权限）；
2. 安装 Visual Studio Community 2026——通过Microsoft.WinGet.DSC/WinGetPackage资源安装Microsoft.VisualStudio.Community；
3. 安装 WinUI / Windows App SDK 相关工作负载——通过Microsoft.VisualStudio.DSC/VSComponents资源安装ManagedDesktop（托管桌面）、Universal（通用）工作负载，以及Microsoft.VisualStudio.ComponentGroup.WindowsAppSDK.Cs（Windows App SDK C# 组件），并显式声明dependsOn: Visual Studio保证安装顺序。

配合 SKILL.md 中的执行命令：

winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity

在 skill 目录下执行（相对路径保持config.yaml），即可实现一键式的环境引导与修复。这正是参考文档要求"把 config.yaml 当作捆绑的 WinGet 引导源"的实际含义：机器准备不再是手工点选，而是声明式配置。

4. 项目选择指南：packaged 与 unpackaged 的完整决策树

这是本参考文档的核心价值所在——在写任何代码之前，先把打包模型定下来。

4.1 选择 packaged（打包应用）的情况

• 用户想要WinUI 3 的默认路径、轻松的本地F5 调试工作流，或Store 友好的分发方式——此时保持脚手架默认配置即可；
• 应用在正常运行期间需要包标识（package identity）或依赖包标识的 API。

4.2 选择 unpackaged（非打包应用）的情况

• 用户期望直接启动.exe可执行文件；
• Agent 驱动的本地验证——每次修改后需要通过 CLI 快速构建并运行验证；
• 需要与既有安装程序或外部位置集成。

关键原则是：unpackaged 需求应通过 setup 流程显式请求，而不是在项目创建之后再事后转换。文档原文明确："Request that option through the setup flow instead of converting the initial project afterward."

在 SKILL.md 的脚手架命令中，这一选项对应-un|--unpackaged参数：

# 默认（packaged）：不传 --unpackaged，或显式传入 --unpackaged false dotnet new winui -o MyApp --unpackaged false # 需要 unpackaged 时：显式传入 --unpackaged true dotnet new winui -o MyApp -un true

4.3 两种模型下的共同纪律

• 无论选择哪种打包模型，都必须先通过 setup 流程脚手架化，然后基于生成的项目继续开发，而不是复制预先构建好的基线文件；
• 如果后续怀疑启动逻辑或共享资源出了问题，用相同打包模型创建一个全新的对比应用，与dotnet new winui输出做 diff，再决定如何重构——这对应了 foundation-template-first-recovery.md 的模板优先恢复策略；
• 一旦选型确定，启动代码与服务代码必须与所选模型保持一致；
• 模板选择上先选标准空白应用（blank app）模板，随着应用成熟再逐步叠加导航、标题栏或窗口化模式——不要一开始就堆砌结构。

4.4 模板验证与脚手架全流程

结合 SKILL.md，首次建项目的完整命令序列是：

# 1. 执行捆绑引导配置（启用开发者模式、安装 VS 与工作负载） winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity # 2. 验证 winui 模板可用 dotnet new list winui # 3. 脚手架化 dotnet new winui -o MyApp # 4. 验证新脚手架：确认项目文件存在并构建 dotnet build MyApp\MyApp.csproj

dotnet new winui模板支持以下选项（SKILL.md 明确列出，未列出的旗标不得臆造）：

注意：skill 规定默认不启用--force，除非用户明确要求覆盖现有文件。这是对"脚手架是受保护基线"理念的执行。

5. 环境审计的兜底：只读检查四分类法

参考文档强调"未经验证不得给出机器就绪建议"。若用户只要求审计、拒绝改动机器，则按 foundation-environment-audit-and-remediation.md 执行非变更式（non-mutating）手动审计，并把结果按四类汇报：

• present（已具备）——OS 版本与构建号、开发者模式状态、dotnet --list-sdks输出、dotnet new list winui结果、Visual Studio 版本、Windows SDK、MSBuild 可用性；
• missing（缺失）——明确不满足的必需项；
• uncertain（不确定）——无法确认的信号必须如实标注为不确定，不得伪装成功；
• recommended optional tools（推荐可选工具）——如 WinGet、Hot Reload、Live Visual Tree 等。

正常 C# WinUI 3 开发的必需项为：受支持的 Windows 构建版本、带 WinUI C# 支持的 Visual Studio、Windows SDK 10.0.19041.0 或更高、可用于 XAML 编译的 MSBuild、.NET SDK 6 或更高；通常可选但推荐的包括开发者模式、WinGet、Visual Studio 调试功能。

6. 引导流程失败时的分级处置策略

参考文档明确反对"猜测式修复"，要求按失败程度分级处理（对应 foundation-environment-audit-and-remediation.md 的 Remediation Strategy）：

1. 缺少任一必需前提：审计类请求需先征得确认，再运行 setup-and-scaffold 流程；
2. 引导部分失败但工具链可用：如实记录部分失败，若当前任务可继续则继续；
3. 引导失败且必需项仍缺失：可用手动审计命令补充细节，然后停止并明确报告阻塞点，不得发明替代安装方案；
4. Windows 构建版本不受支持：先升级 Windows——WinUI 引导命令不能替代 OS 要求；
5. 开发者模式未启用：说明当前任务是否需要它；若需要，优先走捆绑流程或让用户手动开启。

配套的模板优先恢复循环（详见 foundation-template-first-recovery.md）则负责"项目已建但构建/启动失败"的场景：用同打包模型临时脚手架一个对比应用（如dotnet new winui -n RecoveryReference -o RecoveryReference --use-slnx false --no-solution-file false），仅对App.xaml、App.xaml.cs、MainWindow.xaml、合并资源字典等启动区做 diff，回退到模板形态直至干净构建，再以小增量重放自定义代码。这正是参考文档"不要复制预构建基线文件"原则的落地方案。

7. 决策审查清单（Review Checklist）

参考文档以一张五问清单收尾，作为每次选型完成后的自查：

• 机器基线是否确实通过 SKILL.md 中的 setup-and-scaffold 流程验证过？（不是"看起来行"）
• 所选打包模型是否是有意为之的决策？
• 启动工作流是否与所选打包模型匹配？（packaged 走 VS 部署/F5，unpackaged 走 CLI 直接启动）
• 应用是否仍然植根于标准 WinUI 模板，除非确有理由偏离？
• 建议是否与C# 优先的 WinUI 3 工作流保持一致？

这五条与 SKILL.md 的环境规则相互印证："环境就绪、打包选择、应用启动验证是三个独立的检查项，通过一个不代表通过另一个"——即便dotnet build成功，也必须真实启动应用、确认出现顶层窗口等客观启动信号，才算验证完成。

8. 小结

从零开始一个 WinUI 3 项目，正确的顺序是：验证机器基线 → 运行捆绑引导 → 校验模板 → 脚手架化 → 构建并启动验证，而这一切的前提是尽早、有意地决定 packaged 还是 unpackaged。winui-app Skill 通过 foundation-setup-and-project-selection.md（决策依据）、SKILL.md（执行流程）、config.yaml（自动化引导）三份文件把这条路径固化为可重复、可审计、可恢复的工程规范——这正是本文所依据的完整事实链条。读者按本文顺序执行，即可获得一个植根于官方模板、打包模型明确、能够被客观验证启动的 WinUI 3 项目起点。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills