互联网编程做 .NET 桌面应用程序开发这些年，我几乎每到一个新项目都会遇到同一个问题：自动更新怎么做。无论你是在写 WinForms、WPF，还是基于 .NET Framework 的维护型项目，只要软件发出去，用户手里跑的不是你本地那份“最新代码”，更新机制就躲不掉。客户不会主动去官网下载新包，也不会看你发的更新说明，他们只会在程序里点“检查更新”这个按钮，然后期望一切自动完成。这篇就把我从零手写更新器、到集成第三方库、再到维护更新通道这整个过程里的经验和踩过的坑，完整分享出来。
这篇文章适合几类读者：正在给 .NET 桌面应用设计更新方案的开发者；遇到更新后文件被占用、证书不信任、杀软误报等问题的排查者；以及想搞清楚 Squirrel、AutoUpdater.NET、ClickOnce 这些方案到底有什么区别、该选哪个的技术负责人。我会尽量把每个方案的原理、选型逻辑和实操细节讲透，而不是只给你贴一段代码。
1. 先想清楚：五种主流更新方案各自的定位
选择更新方案之前，得先弄清楚一件事：你需要的是一次性的发布渠道，还是一个长期的更新机制。很多项目在初期图省事，直接用“让用户下载安装包手动装”，结果发版一两个月就开始被用户投诉“又要重新装”。我建议在架构设计阶段就把更新链路定下来，后面会省掉大量返工成本。
1.1 从零手写：最灵活也最费心的方案
手写更新器的核心思路是：自己管理更新清单、文件下载、版本校验和替换逻辑。它的最大优势是完全可控，更新频率、更新范围、UI 交互、回滚策略都可以按照项目需求来定制，不受第三方库的约束。
但代价也很明显：你要自己处理的东西远比想象中多。版本号比较不能直接用字符串比；下载过程中断需要重试和断点续传；更新文件被主程序占用需要设计独立的更新流程；下载下来的文件还得做哈希校验防止损坏；一旦更新到一半失败，还要有办法回滚到上一个可用版本。
我见过不少团队在这上面翻了车。最常见的错误是让主程序自己覆盖自己，结果 Windows 文件锁直接导致更新失败。还有人把更新包做成 zip 后直接解压覆盖，却不处理正在运行的程序集，最后进程崩溃。如果你决定手写，至少要把这些边界情况都覆盖住，我会在第二节详细讲。
1.2 集成更新库：AutoUpdater.NET、Squirrel.Windows 与 Velopack
如果不想从零开始，NuGet 上现成的更新库可以大幅缩短开发时间。这几种库的定位差别很大，选错了后面很难受。
AutoUpdater.NET 是最轻量的一种，适合在已有项目里快速接入。它的工作方式是：程序启动时或者点击按钮时，从一个 XML/JSON 地址拉取更新清单，发现有新版本就弹出更新提示，下载安装包或者更新文件后引导用户重启完成更新。它灵活、简单，嵌到现有 WinForms/WPF 项目里非常方便，但它的更新过程依然是“下载文件+替换文件”，文件占用问题仍然需要处理。
Squirrel.Windows 则是另一种思路，它把安装过程做成了一套规范，每次发布都会生成安装器和增量包，更新时通过内置的 UpdateManager 拉取增量并静默安装。它在后期维护体验上更好，但最开始接入时需要改变你的打包和安装方式，学习成本会高一些。Velopack 是 Squirrel 的现代化分支，支持 .NET 6+，维护更积极，如果你是新项目，我更推荐 Velopack 而不是老旧的 Squirrel.Windows。
1.3 平台级方案：ClickOnce 与 MSIX
除了手写和第三方库，还有两个平台级方案经常被忽略：ClickOnce 和 MSIX。
ClickOnce 是 .NET Framework 时代最经典的自动更新方案，开发者在 Visual Studio 里直接把项目发布成 clickonce 应用，然后放到服务器上分发给用户。客户端安装后，每次启动都会检查发布服务器，有新版就自动更新。它最省心的地方是：更新逻辑、安装包生成、版本管理全部由平台完成，几乎不用写代码。缺陷也很明显，权限受限、无法做系统级安装、对老 .NET Framework 应用的支持虽然成熟但到现代 .NET 上已经不再推荐。
MSIX 是微软比较新的打包格式，比 ClickOnce 能力更强，支持增量更新、灵活部署、权限隔离。但它对项目的改造力度比较大，打包签名、证书管理、分发通道都有自己的规范，而且要配合 Windows 应用打包机制来用，不是所有项目都适合迁移上去。如果你想把自动更新做得很“正规”，MSIX 值得调研，但如果只是内部工具，可以先跳过。
我个人对不同场景的建议是：老项目快速迭代，优先用 AutoUpdater.NET 或者干脆手写；新项目重视安装体验和长期维护，直接上 Velopack；团队有资源并且产品要走正规分发渠道，再考虑 MSIX。ClickOnce 除非是历史包袱很重，否则不建议新项目使用。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 自建更新通道：服务端资源设计与客户端更新器实现
这一节我详细讲一下手写更新方案的核心结构。不要觉得自建通道很复杂，其实客户端更新器只需要负责三件事：拉取并解析更新清单、下载差异文件并校验、退出主程序后完成替换和回滚。服务端则更简单，只要提供一个静态文件服务器，放好更新清单和更新包就行。
2.1 更新清单：版本信息与文件哈希的元数据设计
整个更新流程的起点是更新清单（Manifest），它是一个描述“最新版本包含哪些文件、校验值是什么、最低兼容版本是多少”的 JSON 或 XML 文件。我常用 JSON，因为解析方便，而且扩展性比 XML 好。
一个典型的更新清单长这样：
json复制{
"appId": "com.example.desktopproduct",
"channel": "stable",
"appVersion": "2.3.1",
"minSupportedVersion": "2.0.0",
"publishTime": "2025-06-01T10:30:00Z",
"releaseNotes": "修复导出报表时偶发崩溃的问题",
"files": [
{
"path": "MyApp.exe",
"url": "https://update.example.com/packages/v2.3.1/MyApp.exe",
"sha256": "a94f8c5d4b0f3e2b1a9d...",
"size": 5324800
},
{
"path": "Libs/Common.dll",
"url": "https://update.example.com/packages/v2.3.1/Libs/Common.dll",
"sha256": "3b2c0a1e7f8d9c4b...",
"size": 182272
}
],
"installCommand": "MyApp.Update.exe"
}
设计要点有几个。appVersion 是服务端当前版本号，客户端拉取后要和自己当前的版本比较，决定是否更新。minSupportedVersion 很重要，它定义了“客户端最低允许运行的版本”，如果客户端版本低于这个值，必须强制升级，不能跳过，否则可能因为新旧接口不兼容导致功能异常。我见过不少服务端只发版本号不强制下限，结果老客户端接新接口直接崩掉。
files 数组里要注意 path 是相对路径，客户端要严格按照这个路径把文件放到自己的根目录下，这样才能做到“按需更新单个文件”。sha256 是更新包或文件的哈希值，下载完成后必须做完整性校验，绝不能在哈希对不上时继续安装。installCommand 是一个可选的扩展字段，用于指定一些下载完成后需要特殊执行的安装指令。普通的 exe、dll 静态替换就不需要了。
服务端部署特别简单，把清单文件和更新包放到一个静态目录，确保 HTTPS 可访问就行。如果你需要多通道，比如 stable、beta、nightly，就在不同目录下放不同清单，这样客户端按渠道去请求对应地址，实现不同用户拉到不同版本的效果。
2.2 客户端更新器的工作流程与代码骨架
客户端更新器通常设计成两个进程：主程序负责检查更新和下载，更新完成后把替换动作交给一个独立的辅助进程。为什么不能主程序自己替换？因为主程序运行时 exe 和 dll 文件都被系统锁定了，Windows 不允许你边运行边覆盖正在使用的文件。这就好比你不能让自己坐的椅子被抽走的同时还稳稳坐着。
更新流程可以抽象成下面几步：
- 启动时或用户点击时，调用更新检查模块，请求更新清单。
- 解析清单，比较版本，判断当前版本是否需要更新。
- 如果需要更新，下载新文件到临时目录（不直接覆盖）。
- 对下载的文件计算 SHA256，与清单中的值比对。
- 校验通过后，把待更新文件列表、备份目录、目标目录写入一个本地配置，然后启动辅助更新进程。
- 主程序正常退出，辅助进程完成备份、替换、清理临时文件，再重新拉起主程序。
检查逻辑的代码骨架我做了一个精简版：
csharp复制public class UpdateChecker
{
private readonly HttpClient _httpClient;
public UpdateChecker(HttpClient httpClient)
{
_httpClient = httpClient;
}
public async Task<UpdateManifest?> CheckAsync(string manifestUrl)
{
var json = await _httpClient.GetStringAsync(manifestUrl);
var manifest = JsonSerializer.Deserialize<UpdateManifest>(json);
if (manifest == null) return null;
var currentVersion = Assembly.GetExecutingAssembly().GetName().Version;
var latestVersion = Version.Parse(manifest.AppVersion);
if (latestVersion <= currentVersion)
return null;
if (currentVersion < Version.Parse(manifest.MinSupportedVersion))
manifest.ForceUpdate = true;
return manifest;
}
}
这里有几个容易踩的细节：
第一，版本号比较一定要用 Version.Parse，不能直接拿字符串去比，因为“2.10.0”和“2.9.1”字符串排序结果跟语义化版本完全是两回事。如果你用了 SemVer 格式的版本号，比如 2.3.1-beta，Version 解析就不兼容了，这种情况建议引入 NuGet.Versioning 包里的 SemanticVersion 类型。
第二，manifest 里拿到最新版本后，要判断是否需要强制更新。判断条件就是客户端当前版本是否低于 minSupportedVersion。这一步如果做错，老版本客户端会一直忽略更新，直到某天联调时才发现接口已经不兼容。
第三，更新检查频率要合理。一般启动时检查一次就够了，必要的话可以加定时器在后台静默检查，但是不建议每次启动都弹出更新窗口，用户体验会很烦躁。
2.3 文件校验、下载恢复与回滚机制的细节
下载是更新链路里最容易出问题的一环。网络不好、服务端中断、代理拦截，任何一个因素都可能导致下载下来的文件不完整。热搜词里出现的 net::ERR_INCOMPLETE_CHUNKED_ENCODING 是浏览器请求被中断时的报错，在桌面应用的下载场景里，对应的问题就是“流读着读着断了”，而且在 HttpClient 里还不一定抛出异常，可能只是拿到一个比预期短的文件。所以下载完成后必须算哈希比对。
文件校验代码：
csharp复制public static async Task<string> ComputeSha256Async(string filePath, CancellationToken token = default)
{
using var stream = File.OpenRead(filePath);
using var sha256 = SHA256.Create();
var hashBytes = await sha256.ComputeHashAsync(stream, token);
return Convert.ToHexString(hashBytes);
}
public static bool VerifyFile(string filePath, string expectedHash)
{
var actual = ComputeSha256Async(filePath).GetAwaiter().GetResult();
return string.Equals(actual, expectedHash, StringComparison.OrdinalIgnoreCase);
}
如果你的更新包比较大，比如上百 MB，一定要实现断点续传。HttpClient 默认的 GetAsync 是不支持断点的，你需要手动加上 Range 请求头：
csharp复制var request = new HttpRequestMessage(HttpMethod.Get, downloadUrl);
request.Headers.Range = new RangeHeaderValue(existingLength, null);
我已经踩过一次坑：一个 300MB 的安装包，用户网络不稳定，下载到 80% 断掉，重试又要从头开始，下载了三次全失败。后来加了断点续传，虽然还是会断，但每次能接着续，总耗时缩短了一个数量级。
再来说回滚。很多人做更新只想着怎么“更新成功”，很少想“更新失败怎么办”，直到现场客户反馈开不了机才后悔。最简单可靠的回滚策略是：替换前把旧文件全部复制到一个备份目录，然后执行替换。如果替换过程抛异常，辅助进程立刻从备份目录恢复文件。备份保留策略可以做到最近两个版本，防止发布的新版本身有问题导致连环翻车。
备份和替换用最简单的文件操作就行：
csharp复制// 备份旧文件到 backup/v1/
Directory.CreateDirectory(backupDir);
foreach (var target in updatedFiles)
{
var source = Path.Combine(appDir, target);
if (File.Exists(source))
{
File.Copy(source, Path.Combine(backupDir, target), true);
}
}
// 复制新文件
foreach (var target in updatedFiles)
{
var newFile = Path.Combine(packageDir, target);
var destFile = Path.Combine(appDir, target);
Directory.CreateDirectory(Path.GetDirectoryName(destFile));
if (File.Exists(newFile))
{
File.Copy(newFile, destFile, true);
}
}
注意备份和替换都必须在辅助进程里完成，因为主程序退出后文件锁才释放。如果你用安装包形式更新，辅助进程还可以兼任“卸载旧版本——安装新版本”的任务，通过启动参数传一个执行命令即可。
3. 用现成库把更新功能跑起来：落地配置与打包细节
自建方案虽然灵活，但对于大多数项目来说，集成一个成熟的更新库能省掉非常多细节。市面上常见的几个库我都实际试过，下面把接入方法和它们的边界讲清楚。
3.1 AutoUpdater.NET：快速接入与埋点注意事项
AutoUpdater.NET 的接入非常快。首先通过 NuGet 安装 AutoUpdater.NET，然后在程序入口处调用：
csharp复制AutoUpdater.Start("https://update.example.com/update.xml");
这个库默认会读取一个 XML 格式的 appcast，格式大致如下：
xml复制<item>
<version>2.3.1</version>
<url>https://update.example.com/packages/v2.3.1.zip</url>
<changelog>修复导出报表偶发崩溃的问题</changelog>
<mandatory>false</mandatory>
</item>
调用时机需要注意，不要放在窗体的构造函数里，建议放在主窗体 Shown 事件或者单独的检查按钮触发，避免界面还没出来就被弹窗打断。AutoUpdater.NET 对事件的支持比较完善，你可以这样处理更新过程的关键节点：
csharp复制AutoUpdater.CheckForUpdateEvent += (args) =>
{
// 这里返回 true/false，控制是否继续执行后续更新
};
AutoUpdater.DownloadProgressChanged += (sender, e) =>
{
progressBar.Value = e.ProgressPercentage;
};
AutoUpdater.InstallerLaunched += (sender, e) =>
{
// 安装器已经开始运行，主程序可以安全退出了
Application.Exit();
};
实际使用中我踩过的坑主要是：默认的 XML 更新源如果服务器返回了非 200 状态码，库可能只是静默失败，不会给用户任何提示。要记得把检查失败的情况也反馈出来，避免用户以为没有新版本。另外，如果你发布的是单文件 exe，注意 AutoUpdater.Start 要放在单文件启动器的真正入口处，不能放在会被提前 return 的分支里，否则永远检查不到。
AutoUpdater.NET 适合那种“在线更新 zip 包，然后退出程序、解压、重新启动”的轻量场景。如果安装包内容太多、需要自定义安装界面、需要系统级安装，它就不够用了。
3.2 Squirrel.Windows / Velopack：增量打包与安装器体验
Squirrel.Windows 系列和 AutoUpdater.NET 是两类东西。AutoUpdater.NET 只是“下载 + 解压 + 替换”，而 Squirrel/Velopack 提供了一整套“增量发布 + 安装器管理 + 快捷方式管理”的解决方案。
Velopack 的使用流程大致是：
- 在项目里安装 Velopack 打包工具依赖。
- 执行打包命令生成安装器和发布目录。
- 客户端启动时调用更新检查 API。
举个例子，用 Velopack 打出安装包的命令大致是：
bash复制vpk pack -o packages -p publish/ -v 2.3.1
它会在 packages 目录下生成一组文件，包括 nupkg 包、安装器、以及 delta 增量包。客户端更新时只需要下载 delta 包，体积通常小很多，尤其适合每个版本都在频繁发补丁的团队。
客户端接入代码：
csharp复制using (var mgr = new UpdateManager("https://update.example.com/velopack/"))
{
var updateInfo = await mgr.CheckForUpdatesAsync();
if (updateInfo != null)
{
await mgr.DownloadUpdatesAsync(updateInfo);
mgr.ApplyUpdatesAndRestart();
}
}
Squirrel 和 Velopack 的安装模型是把应用安装到用户目录，不依赖管理员权限，也不写系统注册表，所以对审核和杀软更友好，卸载也更干净。如果你的应用要作为一个正式桌面软件分发给大量用户，这套机制成熟度远高于手写方案。
使用 Velopack 时有一个关键点：你的应用会以“安装模式”首次运行，用来创建快捷方式和注册启动项。这会导致同一份入口代码在“安装时”和“正常启动时”都被执行，你需要在入口处判断运行模式，避免用户数据被初始化两次。
csharp复制if (VelopackApp.HandleArgs()) return;
这行代码建议放在 Main 方法第一行，它会自动处理安装/更新/卸载的参数。很多新手没注意到这一步，导致每次更新都触发一遍初始化逻辑，轻则多弹窗，重则覆盖用户配置。
3.3 桌面环境的边界问题：权限、证书与文件占用
不管用哪种库，有几个桌面环境特有的问题绕不开。
第一个是文件占用。如果主程序正在运行，更新库去覆盖 exe 或 dll 一定会失败。不管是手写更新器还是 AutoUpdater.NET，本质都是“先退出主程序，再替换文件”。Squirrel/Velopack 通过安装器进程规避了这个问题，所以它们在更新体验上更稳。
第二个是权限。如果你的软件安装到了 Program Files 目录，更新时没有管理员权限就写不进去。Squirrel/Velopack 选择安装到用户目录就是为了规避这个痛点。手写方案如果被迫装在 Program Files 下，就需要在更新时触发 UAC 提权。提权本身不难，但频繁弹 UAC 会很影响用户体验，最好做成一次性提权后完成整个更新。
第三个是代码签名和证书。Windows 对未签名的 exe 信任度很低，SmartScreen 会拦截，杀软也可能误报。更新包里的新 exe 如果没签名，很多用户机器上会被直接拦截。我建议给更新包和更新器全部做代码签名，签名证书的信任链要完整，否则又会出现热搜里“已处理证书链，但在不受信任的根证书”这类问题。
自研更新器尤其要注意签名问题。就算你自己写了一个内部小工具，只要它出现在用户桌面，杀软就会扫描它。如果它没有签名且行为是“下载文件+覆盖exe”，很容易被杀软判定为可疑程序。解决方式没有捷径，就是签正式代码签名证书，并且更新器本身要带上版本信息。
4. 自动更新过程中的典型故障与排查思路
自动更新上线后，真正的挑战才开始。用户环境千奇百怪，网络、系统、杀软、代理、权限任何一个环节出问题，更新就会卡住。我在维护更新通道的过程中积累了下面这些排查经验。
4.1 下载中断、文件损坏与校验失败
下载中断是我遇到最多的故障。用户网络慢、代理超时、服务端带宽耗尽，都会导致下载到一半失败。表面上 HttpGet 返回了 200，但响应内容被截断，或者 TLS 连接被重置。
排查思路是先用一个原始下载工具（比如浏览器直接下载更新包）确认服务端文件本身没问题，然后在客户端日志里记录实际下载大小和预期大小的差距。客户端日志至少要包含：清单下载地址、HTTP 状态码、实际接收字节数、校验哈希值。没有日志，你根本没法远程判断用户卡在哪一步。
我在自研更新器里养成了一个习惯：增加“重试 + 退避”机制。每个文件下载失败后，延迟几秒重试，最多重试三次。文件校验失败后直接删除本地缓存重新下载，不要反复用同一份损坏文件去覆盖旧文件。如果某个文件重试多次都不行，主动停止更新，并把失败原因写进日志，更新状态标记为“可重试”，避免进入“无限循环更新”的尴尬局面。
4.2 用户环境差异：杀软误报、网络代理、证书信任
杀软误报是更新机制最容易遇到的外部干扰。一个正常的更新器如果行为比较激进，比如频繁写 exe、替换文件、修改注册表，杀软很可能直接拦截。这种情况下你给用户打电话解释“不是病毒”是没用的，正确的做法是从技术层面规避：
- 所有文件签名；
- 更新器只用合法的文件操作，不碰计划任务、不注入其他进程；
- 敏感操作尽量走 Squirrel/Velopack 这类有名的开源流程，避免自研逻辑过于“神秘”。
网络代理是大坑。企业用户的电脑普遍有代理，如果你的更新服务走的是 HTTPS，但代理做的是中间人解密，客户端拿到的证书链就可能异常，报“不受信任的根证书”。排查时先让用户直接用浏览器访问更新地址和清单地址，看是否访问正常；如果浏览器也异常，说明是代理的证书信任问题，而不是应用代码的问题。
证书链问题还有一种情况是：更新服务器本身用了自签名证书，但客户端没有把这个证书加到受信任根目录。Windows 日志里会出现“证书链正确，但不信任该根”之类的提示。这种不是开发环境可以随便忽略的，生产环境一定要用公共受信任的 CA 证书，不要用自签名糊弄。
4.3 更新后程序启动不了：回滚策略设计
最严重的故障不是更新失败，而是更新“看起来成功”但程序启动不了。常见原因包括：新版本依赖的某个 dll 没有随包发出来、配置文件被覆盖、.NET 运行时版本对不上、新版本在部分系统上初始化失败。
我遇到过最典型的一个场景：新版本引用了某个更高版本的 native dll，开发机没问题，但客户机器上缺失，程序启动直接报错。更新器却认为替换已经成功，于是用户被困在一个不可用的版本里。
解决办法是把回滚做成强制策略，而不是可选项。我通常的做法：
- 更新前创建“版本状态”标记，写入本地数据库或 JSON，标记当前版本号和备份位置。
- 更新后启动主程序时，增加一个启动前检查，如果主程序启动后 30 秒内没有主动将状态标记为“启动成功”，下一次启动就自动触发回滚。
- 回滚逻辑放在更新器里，从备份目录恢复上一个版本，并记录回滚原因。
当然，手动写这套逻辑工作量不小。这也是为什么很多团队直接用 Velopack，它本身就内置了更新失败后的回滚机制。但这不代表你可以不看文档就上线，至少得理解它的回滚触发条件是什么，不然出了问题还是抓瞎。
5. 版本策略与灰度发布：让更新这件事可持续
更新机制稳定运行后，下一个要解决的问题是“怎么发布”。很多团队把整个更新流程做出来了，但在版本策略上很粗糙，导致用户被强制更新、或者新版偷偷上线没人知道。下面这些策略是我在实际项目中逐渐摸索出来的。
5.1 强制更新、可选更新与静默更新的使用场景
更新提示弹窗要根据版本差异来判断，不能千篇一律。我的经验是分三种模式：
- 可选更新：一般是小版本迭代，比如 bug 修复、性能优化，当前版本仍然能用，就提示用户“有新版本可以更新”，用户可以拒绝。
- 强制更新：一般是大版本或者有不可兼容变更时，比如接口重做、数据格式变更、安全漏洞修复。此时用户必须升级，否则影响正常使用。判断依据是服务端清单里的
minSupportedVersion。 - 静默更新：适用于用户无感知的 bug fix 或内部工具场景，后台自动下载，下次启动时自动替换，不打扰用户操作。
这三种模式可以并存。比如我现在的产品里，小版本默认静默更新，功能增强弹可选提示，涉及数据迁移的版本强制更新。判断逻辑集中在一个更新策略服务里，不在客户端写死，这样服务端可以通过清单字段随时调整，不用发版客户端代码。
5.2 增量更新与差分合并的思路
如果每次更新都是全量下载几十 MB 甚至上百 MB 的安装包，用户网络差一点就会崩溃。增量更新是减少下载量的关键手段。
最简单的增量是“文件级增量”：更新清单里只列出变化过的文件，客户端下载时也只下载这些差异文件。它要求你发布时能算出两个版本之间哪些文件有变化。实现思路也不复杂，CI 发布时把新旧两个版本的包逐文件计算哈希，把哈希不同的文件打进增量包。
再进一步是“二进制差分”，比如用 bsdiff 之类的算法对单个文件做差异补丁。这个方案压缩率更高，但复杂度也更高，而且升级链路里每一步都要做兼容测试。绝大多数桌面应用做到文件级增量就够了，不要一上来就追求极端差分。
我用文件级增量的体感是：界面布局和交互逻辑常变的项目，每次增量包一般只有 1~5 MB；如果某个版本底层依赖升级，单个 dll 改动大，增量包会大一些，但仍然比全量小很多。用户下载更新从“等一分钟”变成“几秒”，体验提升非常明显。
5.3 灰度发布与客户端埋点统计
灰度发布是自动更新系统上线后最重要的一项升级。没有灰度，你一次把所有用户推到新版本，出了严重 bug 就是生产事故；有灰度，可以让 5% 的用户先更新，观察数据和反馈，再逐步放大比例。
实现灰度不需要太复杂。最简单的方式是按用户 ID 或者机器码哈希取模，在服务端清单接口根据请求参数决定是否返回新版本。比如：
csharp复制var bucket = Math.Abs(userId.GetHashCode()) % 100;
if (bucket < grayPercent)
{
return latestManifest; // 返回新版
}
else
{
return stableManifest; // 返回当前稳定版
}
灰度期间一定要有客户端埋点。更新检查成功率、下载成功率、安装成功率、启动成功率，这四个指标必须统计到。一个直接可用的做法是：客户端每次检查更新后把结果上报到一个日志接口，上报内容包含当前版本号、检查结果、下载耗时、文件校验结果。这些数据能帮你快速定位灰度版本是卡在下载阶段还是安装阶段，而不是等用户主动投诉才知道出了问题。
我在灰度过程中踩过最深刻的一个坑是：灰度比例设了 10%，但只按 userId % 100 判断，没有考虑企业内部批量装机的情况。结果某个大客户一次性装了 200 台机器，userId 都是同一个段内的连续值，导致这个客户 200 台机器全部被灰度到新版，而新版刚好有兼容问题，瞬间引发大量工单。后来我把用户 ID 和机器码结合起来做双层分流，客户端哈希值独立分布，才避免类似问题。
再补一个小技巧：灰度发布不一定要“一刀切”到 100%。如果新版稳定运行三天以上，先放到 50%，再观察一天，再放到 100%。宁可多等两天，也不要为了“冲进度”把整个用户群体都推向未知风险。更新系统的核心目标，从来不是“发版最快”，而是“出问题时损失最小”。
在最终方案定下来之前，我强烈建议你在设计文档里写清楚这四个问题的答案：更新失败时用户看到什么？更新失败后会不会影响旧版本继续使用？新版启动失败有没有自动回滚？回滚后用户数据会不会丢？如果这四个问题都有明确答案，你的自动更新方案基本就合格了。