做桌面交付这行久了，判断一个项目"能不能交出去"的标准，早就不是编译通过，而是客户机器上双击那一刻会不会弹出一个看不懂的对话框。这几年我经手的项目里，出现频率最高的一类工单就是"程序打不开"，而九成情况下，答案都指向同一个东西——.NET Windows Desktop Runtime。它不是一个可以忽略的安装附带品，而是决定你这套 Windows 应用能不能跑、跑多快、升级会不会翻车的地基。

很多人对它的认知还停留在"装个运行库"的层面，觉得它就是个前置条件，装完就完事。实际上从 .NET Core 3.0 把 WPF 和 WinForms 搬到新底座上开始，这个运行时的形态、分发方式、版本策略都发生了根本性变化，桌面应用的交付模型也跟着变了。它把过去那种"机器上有个全局大仓库，所有程序共享"的模式，改成了按大版本隔离、可以与应用程序同行的模式；它把桌面库从主运行时里拆出来单独发包，让服务端程序不必背着几百兆的图形栈；它让"自带运行时"从一件很土的事情变成了默认推荐。

这篇内容适合三类人看：正在做 Windows 桌面交付、被环境差异折磨过的开发者；准备从旧框架迁移、需要评估风险的技术负责人；以及刚接触这套栈、想知道"为什么我的 exe 在别人电脑上打不开"的新手。我会从运行时到底是什么讲起，一路讲到发布模式取舍、版本滚动行为、启动优化和真实排障链路，中间穿插我自己踩过的坑。

1. 先弄清楚装进去的到底是什么：Desktop Runtime 与 SDK 的边界

1.1 一次"双击没反应"的现场复盘

印象很深的一次，某公司内网部署一套用 WPF 写的设备管理客户端，开发机上跑得好好的，到了现场机器上，双击图标之后弹出一个系统对话框，大意是"要运行此应用程序，需要安装以下版本之一的 .NET"。现场同事的第一反应是"是不是没装 .NET"，于是装了一个 .NET SDK，装完确实能跑了，于是这事就被记成"以后装 SDK 就行"。

这个结论是错的，而且错得挺贵。SDK 里包含运行时，所以装 SDK 在开发场景下确实能让程序跑起来，但一台纯客户端机器上装 SDK，等于把一个完整的编译工具链、模板、包管理器、MSBuild 全塞进去了，体积比运行时大好几倍，还白白扩大了攻击面。更要命的是，SDK 默认可能装的是某个具体的小版本，而应用真正需要的只是"8.0 这一条线上的任意一个补丁版本"。

要分清楚这两个东西，最直观的方式是记住分层：SDK 是给开发机用的，Runtime 是给运行机用的。SDK 里面嵌套了 Runtime，反过来不成立。交付机器上永远只需要 Runtime，而且只要 Desktop Runtime 这一种。

还有一层容易混淆的是"运行时"和"框架"。日常口语里大家混着说，但在配置文件里它们是明确的：Microsoft.NETCore.App是基础运行时，提供 GC、JIT、BCL、线程池这些；Microsoft.WindowsDesktop.App是桌面运行时，提供 WPF 和 WinForms 的那套程序集。一个控制台程序只需要前者，一个 WPF 程序两者都要。

1.2 共享框架的分层结构：为什么桌面库要被单独拆出来

在旧框架时代，整个框架是一个整体，装在系统目录里，所有程序共享。这种设计在单机时代没什么问题，但到了服务端和容器时代就变成了负担——一个跑在 Linux 上的 Web 服务，凭什么要背着 WPF 的 PresentationFramework、PresentationCore，还有一堆和图形、打印、输入法相关的东西？

新的做法是把基础运行时和桌面库拆成两个共享框架，各自独立发包。服务端应用只依赖基础运行时，镜像能小一大截；桌面应用按需加上桌面框架。这个拆分带来的副作用是：桌面应用第一次需要显式声明"我要用桌面框架"，这就是为什么项目文件里会出现net8.0-windows这种带后缀的目标框架，以及<UseWPF>true</UseWPF>、<UseWindowsForms>true</UseWindowsForms>这类属性。

这两个属性不是装饰，它们会实际影响编译：打开UseWPF之后，XAML 编译任务会被挂进构建流程，Page、ApplicationDefinition这些项才会被识别；打开UseWindowsForms之后，设计器相关的程序集引用和源生成器才会生效。我见过有人手工加<Reference>引 WPF 程序集，然后疑惑为什么 XAML 里的x:Class生成不出对应的InitializeComponent，问题就出在这里。

框架引用最终会被写进产物里的runtimeconfig.json，运行时启动时读这个文件，去共享框架目录里找匹配的版本。这个查找过程是你排查一切"找不到运行时"问题的起点。

1.3 三分钟自查：机器上到底装了哪些运行时

排障的第一步永远是先看清楚现状，别急着装东西。最可靠的一条命令是：

dotnet --list-runtimes

输出大概长这样：

Microsoft.NETCore.App 8.0.10 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] Microsoft.WindowsDesktop.App 8.0.10 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App] Microsoft.AspNetCore.App 8.0.10 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]

看三件事：有没有Microsoft.WindowsDesktop.App这一行、大版本号对不对、补丁号够不够。很多人只看到有Microsoft.NETCore.App就以为齐了，其实桌面程序缺的恰恰是另外那一行。

如果机器上根本没有dotnet命令，也不要慌，那只是说明 PATH 里没有，共享框架可能照样装着。这时候去注册表里看更准：

HKEY_LOCAL_MACHINE\SOFTWARE\dotnet\Setup\InstalledVersions\x64\sharedfx\Microsoft.WindowsDesktop.App

这个键下面会列出所有已安装的版本号。32 位应用看的是x86分支，别搞混了——这是另一个高频事故点：64 位机器上装了 x64 运行时，结果应用是 AnyCPU 但在某个环节被强制成了 x86，启动时照样报缺运行时。

提示：检查的时候顺手确认一下应用的位数。dotnet --info会打出当前宿主的环境信息，包括 RID，对着看比猜快得多。

2. WPF、WinForms 共用底座之后，桌面技术栈的边界发生了什么变化

2.1 共享框架里到底装了哪些东西

Microsoft.WindowsDesktop.App这个目录打开看一眼，信息量很大。里面有PresentationFramework.dll、PresentationCore.dll、WindowsBase.dll，这是 WPF 的三件套；有System.Windows.Forms.dll、System.Drawing.Common.dll、System.Windows.Forms.Design.dll，这是 WinForms 那一套；还有System.Xaml.dll、UIAutomationClient.dll、ReachFramework.dll（打印相关）、PresentationFramework.Aero2.dll这类主题程序集。

看清楚这个清单有两个实际用处。第一个是判断依赖：如果你的项目里第三方控件库引用了某个桌面程序集，你能快速确认它要求的最低版本。第二个是排查"类型找不到"：比如某个老库用了System.Drawing里的 API，在 .NET 6 之后System.Drawing.Common被限制为仅 Windows 可用，如果你的目标框架没带-windows后缀，编译期就会警告甚至报错。

这里有个容易被忽略的细节：System.Drawing.Common虽然在桌面框架里，但它在跨平台语境下曾经是可以用的，后来被加上了平台限制。这个变化的连锁反应是，一些做图像处理的库不得不改依赖，或者干脆自己实现。我在一个批量图片处理的小工具上就遇到过，升级目标框架之后原来的缩略图代码全挂，最后换成了基于 WIC 的方案。

2.2 一个进程里同时跑 WPF 和 WinForms 的代价

技术上完全可行，而且相当常见——毕竟大量企业内部工具都是 WinForms 起家，后来想加点好看的界面，就把 WPF 的ElementHost拖进去，或者反过来用WindowsFormsHost嵌一个成熟的三方控件。

可行归可行，代价得心里有数。最直接的是启动开销：两套 UI 框架的静态构造、资源字典、主题加载都要走一遍，冷启动会明显变慢。我做过一次粗略测量，一个纯 WinForms 的登录窗口，启动到可交互大概 300 毫秒；同样的窗口外面套一层 WPF 宿主，变成 700 毫秒往上。这在平时不算什么，但如果你的应用是被系统在开机时拉起来的，用户感知就很明显。

第二个代价是输入法和焦点问题。WPF 和 WinForms 的输入处理是两套体系，嵌入式场景下WindowsFormsHost里的文本框在中文输入法下的候选框位置、Tab 键顺序、右键菜单归属，都可能有怪异表现。这个问题没有通用解法，只能一个个场景测。

第三个代价是渲染层叠。WindowsFormsHost本质上是一个 HWND 子窗口，它永远浮在 WPF 的渲染层之上，任何 WPF 的透明度、变换、动画都无法作用在它上面。如果你的设计里有个半透明遮罩要盖住整个窗口，那块嵌入区域会像开了个洞一样透出来。

我的建议很直接：新项目不要混用，老项目尽量收敛。如果只是想要 WPF 的样式能力，用 WinForms 自绘也能做到七七八八；如果只是需要一个成熟的表格控件，优先找支持 WPF 的版本，而不是嵌 WinForms 的。

2.3 WinUI 3 为什么不在这个共享框架里

这是被问得最多的一个问题：既然 WPF 和 WinForms 都在Microsoft.WindowsDesktop.App里，为什么 WinUI 3 不在？

答案在于分发模型的差异。WPF 和 WinForms 的程序集是纯托管代码，跟着共享框架走完全没问题。WinUI 3 不一样，它带了一大坨原生组件，包括渲染层、窗口管理、控件实现，这些东西和操作系统的版本、以及一套独立的运行时组件绑得很紧。它走的是另一条路——通过 NuGet 包和一套应用本地部署的组件来分发，跟着应用走而不是跟着机器走。

这个差异带来的实际影响是：WinUI 3 应用不需要装 Desktop Runtime 吗？不完全是。如果它同时用了 WPF 或者依赖了Microsoft.WindowsDesktop.App里的东西，还是需要。但如果是一个纯粹的 WinUI 3 应用，它的运行时依赖是以包的形式跟着应用发布的，装机体验会更"绿色"，代价是包体积更大。

选型上的判断标准我一般这么给：需要深度定制 UI、面向新系统、能接受较大的分发体积，选 WinUI 3；需要兼容较老系统、团队 WPF 经验充足、生态控件依赖重，留在 WPF。WinForms 则留给那些"界面不重要、能快速交付就行"的内部工具。

3. 分发形态的取舍：框架依赖、自包含、单文件、裁剪的组合矩阵

3.1 四种发布模式在体积和启动上的真实差距

这是整个交付环节里最需要算清楚账的地方。我用一个中等规模的 WPF 应用做过对照测试，功能差不多，只改发布参数，数据如下（具体数字随版本和依赖浮动，看趋势就好）：

框架依赖模式体积最小，但把版本管理的责任推给了运维。适合内部统一管控的环境，比如公司域内机器有统一的软件分发系统。缺点是只要有一台机器漏装，就是一张工单。

自包含模式把运行时整个拷进输出目录，装机零依赖，代价是体积暴涨。这个体积不是浪费——Microsoft.WindowsDesktop.App解压出来本身就有一百多兆，加上Microsoft.NETCore.App的几十兆，加起来就是这个量级。

单文件模式是在自包含基础上打包成一个 exe。这里有个必须知道的机制：单文件不是真的把东西塞进内存运行，它首次启动时会解压到临时目录（除非你显式配置了不解压，但那样很多原生库加载不了）。所以"首次启动慢、第二次快"是正常现象，别以为是程序有 bug。开了压缩之后，解压开销更大，冷启动能差出一两秒。

ReadyToRun 是另一回事，它把 IL 预编译成本地代码，减少启动时的 JIT 开销。代价是体积增加三到四成，收益在启动路径长的应用上很明显——我测过的一个启动要加载大量泛型集合的应用，开 R2R 之后冷启动从 1.9 秒降到 1.1 秒。

3.2 项目文件里真正起作用的那几个属性

网上教程经常给一大串属性，实际上核心的就那几个。一个典型的自包含单文件配置：

<PropertyGroup> <TargetFramework>net8.0-windows</TargetFramework> <UseWPF>true</UseWPF> <RuntimeIdentifier>win-x64</RuntimeIdentifier> <SelfContained>true</SelfContained> <PublishSingleFile>true</PublishSingleFile> <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract> <EnableCompressionInSingleFile>true</EnableCompressionInSingleFile> <PublishReadyToRun>true</PublishReadyToRun> <SatelliteResourceLanguages>zh-Hans</SatelliteResourceLanguages> </PropertyGroup>

逐个说清楚为什么要加：

RuntimeIdentifier是必须的，自包含发布必须知道目标平台。win-x64是最常见的选择，如果你的用户群里还有 32 位机器（现在很少了，但工业现场的旧设备还真有），就得出win-x86的包。

IncludeNativeLibrariesForSelfExtract这个属性很关键。WPF 依赖一些原生 DLL，默认情况下单文件打包不会把它们塞进去，结果是发布出来一个 exe，运行时报找不到某个原生库。加上这个属性之后，原生库也会被打进去并在启动时解压。

EnableCompressionInSingleFile是体积和启动速度的权衡。开了能省三成左右体积，代价是首次启动要解压。如果是内网分发、带宽不是问题，我建议关掉，启动体验更重要。

PublishReadyToRun前面说过，看你的启动瓶颈在哪。要注意它和PublishSingleFile组合时偶尔会有一些边角问题，发布完务必在干净机器上实测一遍。

SatelliteResourceLanguages是个小而美的优化。不加的话，运行时会带上几十种语言的资源文件夹，每个文件夹里都是一堆小 dll，白白增加体积和文件数。限定成你需要的一两种语言，目录能干净很多。

3.3 裁剪和 AOT 在桌面栈上的硬边界

这两年问"能不能用 AOT 把 WPF 程序编译成原生 exe"的人特别多，答案很明确：不能。

Native AOT 要求整个调用链在编译期可分析，不能有运行时反射生成代码、不能动态加载程序集。WPF 的 XAML 解析、绑定引擎、模板系统全都重度依赖反射，这套机制和 AOT 的假设直接冲突。WinForms 也好不到哪去，虽然它对 AOT 的阻碍小一些，但目前的官方支持矩阵里也没有把它列为可用组合。

裁剪（trimming）的情况类似但稍好一点。WinForms 在较新的版本里获得了有限的支持，需要显式开启并处理一堆裁剪警告，实际项目里能用起来的不多。WPF 则基本不用考虑，官方明确不支持，强行开只会得到运行时随机崩溃。

所以现实的结论是：桌面应用想要减小体积，走裁剪和 AOT 这条路基本堵死，只能靠精简依赖、去掉不必要的资源、限定语言包。这一点和 Web API 项目完全不同，别拿那边的经验套过来。

如果体积真的是硬约束（比如要通过某些渠道分发，有大小限制），我的做法是：能拆的拆成按需下载的模块，主程序保持精简；图片资源换成压缩格式；第三方控件库挑轻量的用。这些土办法比折腾裁剪靠谱得多。

4. 版本滚动与多版本共存：TargetFramework、RollForward 的真实行为

4.1 同一台机器上多个大版本是怎么共存的

这一点是新的运行时模型和旧框架最大的区别之一。旧框架时代，一台机器上装了 4.8，所有程序都用 4.8，程序没法挑。新模型里，每个大版本是独立的目录，互不干扰。机器上可以同时有 6.0、8.0、9.0 三个Microsoft.WindowsDesktop.App，各自的应用找各自的。

这个设计带来的直接好处是升级不怕连带。你给一个老应用升到 8.0，不用担心里面另一个还在用 6.0 的模块被带崩，因为它们的运行时目录物理隔离。

但共存也有代价：磁盘占用和补丁管理。每多一个大版本就是一百多兆，而且每个大版本的补丁要单独打。我见过一台机器上装了四个版本，光运行时占了六百多兆。这不是大问题，但做镜像的时候要注意。

更重要的是升级策略的选择。这里有个反直觉的结论：不是所有应用都应该跟着最新大版本走。LTS 版本（比如 8.0、10.0）支持周期长，适合长期维护的产品；STS 版本（比如 9.0）支持周期短，适合内部工具、尝鲜项目。给一个要维护五年的产品选 STS，等于给自己埋了个必须两年内再升一次的雷。

4.2 runtimeconfig.json 里那条版本线到底怎么算

应用发布出来之后，YourApp.runtimeconfig.json长这样：

{ "runtimeOptions": { "tfm": "net8.0", "frameworks": [ { "name": "Microsoft.NETCore.App", "version": "8.0.0" }, { "name": "Microsoft.WindowsDesktop.App", "version": "8.0.0" } ], "configProperties": { "System.GC.Server": false, "System.GC.Concurrent": true } } }

注意version写的是8.0.0，不是你实际用的8.0.10。这不是 bug，是设计：它表示"我需要 8.0 这条线上的最低版本"，具体用哪个由运行时的滚动策略决定。

默认策略是LatestPatch，意思是找一个同大版本、同小版本、补丁号最高的。所以机器上装了 8.0.10，应用要 8.0.0，就会用 8.0.10。这个机制保证了安全补丁能自动生效，不需要重新发布应用。

想改这个行为，有两个入口。一是在项目文件里设<RollForward>LatestMinor</RollForward>，这样如果机器上没有 8.0.x，可以往上滚到 8.1.x（如果有的话）。二是环境变量DOTNET_ROLL_FORWARD，适合在部署脚本里临时控制。

注意：滚动只在同一个大版本内是安全的。跨大版本滚动默认是关闭的，也不建议打开——8.0 编译的应用滚到 9.0 上跑，虽然大部分情况下兼容，但行为差异是真实存在的，尤其是序列化、正则、全球化相关的部分。

4.3 升大版本前我会走一遍的检查清单

升大版本这事不能拍脑袋，我一般按这个顺序过一遍：

第一，先看目标框架的支持矩阵。较新的 Windows 10 和 Windows 11 都在支持范围内，但更老的系统版本要单独查，工业现场的机器经常跑着很老的系统，这一步不能跳。

第二，跑一遍依赖树。dotnet list package --include-transitive打出来，重点看有没有停留在旧版本的第三方库。有些控件库只支持到某个大版本，升上去直接编译不过。

第三，重点测这几个区域：序列化（尤其是System.Text.Json的行为变化）、正则表达式（超时行为、某些语法）、全球化与排序（ICU 相关的行为差异）、加密相关 API（默认算法和填充的调整）。这几个是历次升级里最容易出问题的地方。

第四，测一遍真实的安装流程，而不是只在开发机上dotnet run。装一个干净的虚拟机，走完整的分发流程，包括运行时装没装、装的是哪个版本、应用能不能起来。

第五，留好回滚路径。应用配置里保留RollForward的开关，出问题时能快速退回。这一点在批量部署场景下救命。

5. 启动速度、内存与渲染：运行时层面还能做的优化

5.1 冷启动的时间到底花在哪

用户对桌面应用的第一印象就是双击到窗口出现的那几秒。这几秒里发生的事情，拆开来看大致是：加载宿主、读取配置、定位并加载共享框架、加载应用程序集、JIT 编译启动路径上的方法、初始化 UI 框架、构建窗口树、首次渲染。

框架依赖模式下，共享框架的加载是内存映射，很快。真正耗时的是程序集加载和 JIT。这就是 ReadyToRun 起作用的地方——把热路径提前编译成本地代码，省掉 JIT 的时间。

但 R2R 不是万能的。它只对发布时能静态分析到的路径有效，动态生成的代码、泛型实例化还是得 JIT。所以我一般会先用一个简单的计时打点，确认瓶颈在哪：

var sw = System.Diagnostics.Stopwatch.StartNew(); // 在 App 构造函数、OnStartup、主窗口 Loaded 各打一个点 System.Diagnostics.Debug.WriteLine($"milestone: {sw.ElapsedMilliseconds}ms");

打三个点基本就能定位：如果窗口构造前就很慢，是程序集加载或 JIT 的问题；如果窗口Loaded之后才慢，那是业务初始化的问题，和运行时没关系。

还有一种情况是杀毒软件扫描。自包含模式下首次启动会释放大量文件，实时防护会逐个扫，能把启动拖到十几秒。这个问题的解法不是优化代码，而是在部署文档里明确要求把安装目录加入排除列表。这是我在实际项目里遇到过最"冤"的性能问题。

5.2 高 DPI 和渲染模式：那些看起来是 bug 其实是配置的事

高 DPI 的问题在笔记本普及之后变得极其普遍。表现是：在 125% 缩放的屏幕上，界面模糊、文字发虚、控件错位。

根本原因是应用没有声明自己支持 per-monitor DPI。WPF 的解决方式是在应用清单里声明：

<application xmlns="urn:schemas-microsoft-com:asm.v3"> <windowsSettings> <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness> <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true/pm</dpiAware> </windowsSettings> </application>

WinForms 在较新版本里通过生成的ApplicationConfiguration.Initialize()处理，对应项目属性里的ApplicationHighDpiMode，设成PerMonitorV2。

这里有个坑要说清楚：不是设了 PerMonitorV2 就万事大吉。多显示器、不同缩放比例、拖动窗口跨屏的时候，WPF 需要在DpiChanged事件里重新调整布局，图片资源要准备多套分辨率，图标要用矢量。老项目里大量硬编码的像素尺寸，在这些场景下会集体出问题。我的经验是，高 DPI 适配的工作量被严重低估，一个中等规模的 WPF 应用，做完整适配大概要两到三周。

渲染模式是另一个话题。WPF 默认走硬件加速，但在远程桌面、虚拟机、某些老显卡驱动下，硬件加速反而会出问题——表现为界面黑块、闪烁、卡死。这时候可以强制走软件渲染：

System.Windows.Media.RenderOptions.ProcessRenderMode = System.Windows.Interop.RenderMode.SoftwareOnly;

这行代码要放在应用启动最早期，构造函数里都嫌晚。代价是 CPU 占用上升，但至少能用。我的做法是做成配置项，让用户能在启动参数里切换，而不是写死。

5.3 句柄泄漏：桌面应用最隐蔽的一类慢性病

内存涨得慢，用户感受不明显；句柄涨得快，两三天之后程序直接崩，而且崩得毫无征兆。这类问题在长时间运行的桌面应用（看板、监控、工位客户端）里特别常见。

排查的第一步是看数。任务管理器里默认不显示 GDI 对象和用户对象，需要手动添加列。一个正常的桌面应用，GDI 对象数应该在几百到一两千之间波动，如果只涨不跌、稳定突破五千，那就基本可以确定有泄漏。Windows 对单个进程的 GDI 对象配额默认是一万个，到顶就是各种绘制失败。

常见的泄漏源我总结了几类：

• Graphics、Pen、Brush、Font没有using。这是最经典的，尤其是在Paint事件里创建画笔。
• Image.FromFile加载图片之后没有释放。这个方法会锁文件，而且底层持有的 GDI+ 句柄不会自动回收。
• Icon和Bitmap转成IntPtr之后忘了DestroyIcon。跨互操作调用时特别容易漏。
• WPF 里的DrawingVisual或RenderTargetBitmap大量创建不释放。这类不是 GDI 句柄，但会吃非托管内存，表现类似。
• 定时器里重复订阅事件。每次 Tick 都挂一个新的处理器上去，对象图越来越大，间接持有各种资源。

定位手段上，最土也最有效的是二分法：把可疑功能一个个关掉，看句柄增长曲线是否变化。进阶一点可以用性能计数器按进程采样。我一般会先写个小的监控面板，实时显示当前进程的 GDI 对象数、句柄总数、私有内存，放在界面的角落里，开发阶段一直开着。

6. 真实排障链路：从错误码到根因怎么走

6.1 弹出"需要安装 .NET"时先别急着装

看到这个对话框，很多人的第一反应是去下载安装包，装完发现还是不行，或者装完这个应用好了，另一个应用又坏了。正确的顺序是先确认三件事。

第一，确认应用要的是哪个框架、哪个版本。对话框里通常会写明，但有时候被截断。更准的办法是看应用目录下的runtimeconfig.json，frameworks数组里写着什么就是要什么。

第二，确认机器上装的是什么位数。这一点前面提过，但值得再强调一次。x64 机器上如果应用是 x86 的，必须有 x86 的运行时，装 x64 的没用。检查注册表时看清楚x64还是x86分支。

第三，确认版本线对不对。应用要 8.0，机器上只有 6.0 和 9.0，那还是不满足。默认的滚动策略不会跨大版本。

这三件事都确认了，再去装对应版本的 Desktop Runtime。装的时候优先用官方安装包而不是手工解压，安装包会处理好注册表、目录权限、PATH 这些琐事。

如果装完还是报错，去看事件查看器里的应用程序日志，通常会有更详细的信息，包括它尝试找了哪些版本、在哪些路径下找的。

6.2 事件查看器、退出码和那些看不懂的十六进制

桌面应用的崩溃信息不像 Web 服务那样有完整的堆栈日志，很多时候只有一个退出码。几个常见的：

0x80070002是"系统找不到指定的文件"，在运行时语境下通常是某个程序集缺失或者路径不对。0x8007000B是"试图加载格式不正确的程序"，典型场景是位数不匹配，或者把 x64 的原生库放进了 x86 的输出目录。0x80131500开头的一般是托管异常，0xE0434352是 .NET 异常的通用退出码，具体异常得看事件日志里的Faulting module和Exception code附近的信息。

排查这类问题，我有个习惯：先在开发机上复现。把输出目录原样拷到一台干净的虚拟机上跑，如果复现不了，那问题一定在环境差异上，而不是代码。这个判断能省掉大量在客户现场瞎猜的时间。

环境差异的高发点包括：系统的区域设置和语言、默认代码页、字体是否安装、是否有特定的运行库（比如某些 VC++ 运行库）、系统版本、屏幕缩放比例、权限（是否以管理员运行）。这些差异里，区域设置引发的问题最隐蔽——一个依赖小数点格式化的解析逻辑，在德语环境下会因为逗号分隔符直接崩掉。

6.3 "我这能跑，客户那不行"的通用排查顺序

这句话大概是桌面交付里出现频率最高的一句。我的固定顺序是这样：

从干净环境开始。找一个从没装过开发工具的虚拟机，走完整的安装流程。这一步能过滤掉 80% 的问题，因为开发机上往往"碰巧"有某个东西。

对比运行时清单。dotnet --list-runtimes两边各跑一次，逐行对比。差异就是线索。

对比环境变量。DOTNET_开头的变量、PATH里的 dotnet 路径、TEMP目录的位置和权限。这几项出问题的概率不低，尤其是企业环境里 TEMP 被重定向到网络盘的情况，单文件应用解压会直接失败。

抓一次进程启动。用进程监视工具看它到底尝试加载了哪些文件、哪些失败了。这一步比较重，但一旦用上，绝大多数"找不到东西"的问题都能一次定位。

确认权限。安装目录是否可写（单文件应用需要往临时目录写）、是否有软件限制策略拦截了未签名的程序、是否有应用白名单。企业环境里这几条经常是根因。

我印象很深的一次，一个应用在客户那边启动就闪退，日志什么都没有。最后查出来是客户装了一个进程防护软件，把应用目录下的某个原生 DLL 当成可疑文件隔离了，文件还在，但内容被替换成了零字节。这种问题靠看代码永远找不到，只能靠对比文件哈希。

7. 从旧框架迁过来的决策路径

7.1 什么情况下值得迁，什么情况下别折腾

这几年被问最多的问题就是"我这套老系统要不要迁"。我的判断标准比较务实，不看技术潮流，看三件事。

第一，有没有必须新运行时才能解决的问题。比如需要用到较新的语言特性、需要更好的异步和并发支持、需要单文件分发、需要在 ARM 设备上跑、需要和现代库对接。如果有具体的、能说清楚收益的点，迁是值得的。

第二，维护周期还有多长。如果这套系统还能活五年以上，迁移的投入能摊薄；如果明年就要被替换掉，迁过去纯属浪费。我见过一个系统迁到一半项目被砍，白干半年。

第三，团队手上有没有余量。迁移不是一次性动作，迁完之后的一两年里，各种兼容性问题会持续冒出来。如果团队已经被需求压满，硬上迁移只会两边都做不好。

技术上的阻碍，主要在两个地方：第三方依赖和平台特定 API。老的报表控件、老的硬件 SDK、老的加密狗驱动，这些如果只提供旧框架版本的库，迁移就会卡住。有些可以用兼容包绕过去，有些绕不过去，只能找替代品或者自己包一层。

7.2 迁移顺序上，我建议先做这几件事

真要迁，不要一上来就动主工程。我的做法是先搭一个"探路工程"：把主工程里最复杂的那几个模块抽一两个出来，单独建成新框架的项目，跑通编译和基本功能。这个过程能快速暴露依赖问题，成本又可控。

探路工程跑通之后，再按"从边缘到核心"的顺序推进。先迁那些不依赖特殊 API、没有复杂 UI 的模块，比如数据访问层、工具类、日志组件。这些迁完能建立起团队的信心和工具链，也能沉淀出一套可以复用的改造模式。

UI 层放到后面，但不要放到最后。因为 UI 层往往藏着最多的问题——自定义控件、渲染、输入法、打印、剪贴板，每一个都可能是坑。早一点开始测，早一点发现。

还有一件事容易被忽略：安装和升级流程要同步改造。旧框架应用和新的运行时应用，安装方式不一样，升级策略不一样，回滚方式也不一样。如果这块不同步做，等到发布前一天才发现装不上，那就很被动了。

从我个人这几年的实际感受来说，这套运行时模型真正的价值不在于性能提升了多少，而在于它把"应用需要什么"和"机器上有什么"这两件事的关系重新理清楚了。按大版本隔离、可与应用同行、补丁自动滚动，这些机制让桌面交付从一门靠经验的手艺，变得更像一件可以工程化、可以标准化的事情。代价是你要把这些机制搞明白，不能再用"装个运行库就行"的心态对付它。我在多个项目里反复验证过一件事：把这套东西吃透，写进交付文档，装机环节的工单量能下降一个数量级，而这部分省下来的时间，远比研究微优化划算得多。