简介面向需要持续迭代的WPF桌面程序自动更新是降低分发与维护成本的重要能力。这套代码资源围绕C#客户端与Java服务端完整展示了版本检查、更新包下发、下载解压与替换重启等关键机制适合正在为项目加入自动升级功能、或希望学习跨语言更新架构的开发者。包内共248个文件约45.56MB143个cs文件构成客户端核心逻辑13个xaml提供WPF界面21个java文件负责服务端接口另有exe、jar、msi等可执行/安装产物以及json、xml配置文件与说明文档结构清晰便于定位代码与配置。目前已有172人浏览学习属于中小体量、可直接部署调试的工程示例。深入研读可掌握自动更新中的HTTP/HTTPS通信、版本信息解析、文件校验与压缩替换、进程重启等关键技术借助随包代码和配置能够快速复制到自有C#项目或改造成通用更新组件减少重复搭建成本。1. 自动更新不只是下载一个文件在 WPF 上位机和桌面工具开发中自动更新是典型的“看着容易、做着坑多”。很多人最初打算用 WebClient 把新 exe 下载下来覆盖旧文件运行时才发现exe 被进程占用、版本号比较错误、下载断了一半、新版本启动崩溃却没有回滚。这些问题不是网络问题而是协议和流程没设计好。该压缩包是一套 C# 自动更新客户端和 Java 服务端接口的实现源码里包含 BZip2InputStream.cs、BZip2OutputStream.cs、FileManager.cs、BinaryHandle.cs正好串起压缩、解压、文件覆盖、服务端发布。下面按“协议设计 → C# 客户端 → Java 服务端 → 上线收尾”的顺序拆讲适合要在 WPF 项目里做自动更新的开发者。2. 更新协议设计C# 客户端与 Java 服务端先对齐版本状态自动更新最忌讳两端各写各的。客户端用字符串比较版本号服务端只丢一个文件名过来结果上线前联调半天、上线后依然出问题。我接手这类项目时第一步永远是把“清单”定下来服务端返回结构化数据包含最新版本号和下载文件信息客户端拿到后先做逻辑判断再决定是否下载。2.1 用 JSON 清单替代散装的接口参数在 C# 和 Java 之间传更新信息JSON 是成本最低的方式。WPF 客户端用 System.Text.Json 解析Java 服务端用 Spring Boot 的 Jackson 直接输出几乎不引入额外依赖。相比 XMLJSON 字段更短嵌套结构也更直观。下面是我在项目里常用的更新清单字段约定字段类型含义appNamestring应用标识防止多个产品共用一个服务器时串包versionstring服务端认为的最新版本号minVersionstring允许运行的最低版本低于它时必须强制更新downloadUrlstring更新包相对路径客户端拼接服务器地址sha256string更新包 SHA256下载后逐字节校验releaseNotestring更新说明展示在 WPF 的更新弹窗里协议设计的关键一点是 minVersion。如果客户端版本低于 minVersion不能只做“建议更新”必须阻塞旧版本继续运行否则后续接口升级后老客户端可能连服务器都连不上。对应清单 JSON 示例{ appName: HmiScada, version: 1.4.2, minVersion: 1.2.0, downloadUrl: /packages/hmiscada-1.4.2.bz2, sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08, releaseNote: 修复 Modbus 重连偶发失败的问题 }下载地址如果是相对路径客户端必须根据当前环境切换到 http 或 https。内网 WPF 上位机场景大多用 http外网发布必须强制 https否则更新包在链路上被篡改时哈希校验形同虚设。2.2 C# 端版本判断用 Version 类型而不是字符串比较很多 C# 入门项目会把版本号写成字符串然后直接比较。这种做法在“1.9.2”与“1.10.0”之间会翻车因为字符串按位比较时“1.10.0”反而小于“1.9.2”。正确做法是使用 System.Version。我把检查逻辑拆成一个独立方法方便单元测试public CheckResult ResolveUpdate(UpdateManifest? manifest, Version localVersion) { if (manifest is null) return CheckResult.Failure(服务器没有返回更新清单); var remote Version.TryParse(manifest.Version, out var remoteVersion) ? remoteVersion : throw new FormatException($非法版本号: {manifest.Version}); if (remote localVersion) return CheckResult.NoUpdate; var min Version.TryParse(manifest.MinVersion, out var minVersion) ? minVersion : null; bool forced min is not null localVersion min; return CheckResult.Available(remote, forced); }这段代码里先把服务端版本和本地版本都转成 Version再做三次比较无更新、可选更新、强制更新。CheckResult.Available 里带一个 forced 标志UI 层拿到后弹不同的提示框。如果是强制更新WPF 主窗口就不显示“下次再说”按钮直接进入下载流程。提示如果本地程序有可能从“无版本号”状态升级代码里要把本地版本默认成 0.0避免空引用导致更新功能完全失效。2.3 Java 服务端清单接口和文件下载接口分开服务端不需要做复杂业务核心就是读更新清单返回给客户端再把更新包文件以流的形式交给客户端。我通常写两个接口GET /update/manifest 接收客户端上报的版本返回清单GET /update/packages/{fileName} 返回更新包二进制。分开的原因很实际清单接口要求响应快、可以做灰度策略文件下载需要支持大流量方便单独加 nginx 缓存和带宽限制。RestController RequestMapping(/update) public class UpdateController { private final UpdateManifest currentManifest; private final Path updateRoot; public UpdateController(Value(${update.manifest-path}) String manifestPath, Value(${update.root-path}) String root) throws IOException { this.updateRoot Paths.get(root); this.currentManifest readManifest(Paths.get(manifestPath)); } GetMapping(/manifest) public ResponseEntity? manifest(RequestHeader(value X-App-Version, defaultValue 0.0) String clientVersion) { if (compareVersion(clientVersion, 1.0.0) 0) { return ResponseEntity.status(426).body(currentManifest); } return ResponseEntity.ok(currentManifest); } GetMapping(/packages/{fileName}) public ResponseEntityResource package(PathVariable String fileName) { if (!fileName.matches([a-zA-Z0-9._-])) { return ResponseEntity.badRequest().build(); } Path target updateRoot.resolve(fileName).normalize(); if (!target.startsWith(updateRoot) || !Files.exists(target)) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) .header(Content-Disposition, attachment; filename\ fileName \) .body(new FileSystemResource(target)); } }这里有两个容易在 Java 面试八股文里被问到的点。第一客户端版本过低时返回 426 Upgrade Required而不是硬编码 200客户端可以专门捕获这个状态码做强制更新。第二fileName 直接用 PathVariable 拼路径存在目录穿越风险matches 正则过滤加 normalize 后校验 startsWith是 Java 服务端的标准防御姿势。自动更新接口虽然简单安全边界不能省。整个更新协议到这里就闭环了客户端上报版本服务端回清单客户端比较后决定是否下载下载接口用路径参数定位文件。3. 把 C# WPF 自动更新模块做成独立服务协议定完就轮到客户端落地。很多 WPF MVVM 项目会把自动更新直接写进 MainViewModel然后发现界面等待、进度回调、退出重启全搅在一起。我自己的项目里自动更新更像是一个“可独立启动的模块”接收服务器地址和当前版本号经过检查、下载、校验、准备四个阶段最后通过事件告诉界面层该显示什么。3.1 更新服务和 WPF 界面解耦WPF 上位机里 MVVM 是标配加不加 Prism 都有套路。自动更新代码放 ViewModel字段一多就会和业务状态互相干扰。常见做法是定义 UpdateService构造函数传入 HttpClient 和事件回调public class UpdateService { private readonly HttpClient _http; private readonly Version _localVersion; public UpdateService(HttpClient http, Version localVersion) { _http http; _localVersion localVersion; } public event EventHandlerUpdateProgress? ProgressChanged; public event EventHandlerUpdateState? StateChanged; public async Task RunAsync(CancellationToken ct) { var manifest await GetManifestAsync(ct); var decision ResolveUpdate(manifest, _localVersion); if (decision.Kind UpdateKind.None) return; StateChanged?.Invoke(this, UpdateState.Downloading); var packageFile Path.Combine(Path.GetTempPath(), ${manifest.AppName}-{manifest.Version}.bz2); await DownloadPackageAsync(manifest.DownloadUrl, packageFile, ct); if (!VerifySha256(packageFile, manifest.Sha256)) throw new InvalidDataException(更新包哈希校验失败); PrepareUpdate(packageFile, manifest.Version, ct); StateChanged?.Invoke(this, UpdateState.ReadyToRestart); } }更新服务把流程固化成几个阶段获取清单、版本判断、下载、校验、准备。UI 只需要订阅 StateChanged 事件根据 ReadyToRestart 提示用户是否立即重启。WPF 的 Dispatcher 会在事件回调里自动回到 UI 线程不需要额外写 Invoke前提是事件在 UI 线程的同步上下文里触发。3.2 下载更新包流式下载与进度上报下载最大的坑是直接把整个包 ReadAsByteArrayAsync内存占用和 UI 卡死一起出现。我一般用 ResponseHeadersRead 配合 ReadAsStreamAsync一边从网络读一边写磁盘同时通过事件上报进度。这样能避免更新包过大导致内存暴涨也方便在界面上画进度条。private async Task DownloadPackageAsync(string url, string destFile, CancellationToken ct) { using var response await _http.GetAsync(url, HttpCompletionOption.ResponseHeadersRead, ct); response.EnsureSuccessStatusCode(); await using var source await response.Content.ReadAsStreamAsync(ct); await using var target new FileStream(destFile, FileMode.Create, FileAccess.Write, FileShare.None, 81920, true); var buffer new byte[81920]; int read; long received 0; long total response.Content.Headers.ContentLength ?? 0; while ((read await source.ReadAsync(buffer, ct)) 0) { await target.WriteAsync(buffer.AsMemory(0, read), ct); received read; if (total 0) ProgressChanged?.Invoke(this, new UpdateProgress((int)(received * 100 / total))); } }代码里的 81920 字节缓冲区是 80KB对齐 FileStream 默认缓冲区后能减少用户态和内核态的切换。如果更新包经常在 1MB 以下缓冲区可以降到 4096省内存但吞吐量略低。下载路径建议用 Path.GetTempPath() 组合文件名不要放程序目录避免杀毒软件对写入 exe 目录产生告警。3.3 校验、解压和准备更新更新包下载后要先做哈希校验。服务端生成的 SHA256 不能只在浏览器里看要在 CI 或发布脚本里自动算。这里给出一个简单校验函数private static bool VerifySha256(string filePath, string expected) { using var sha SHA256.Create(); using var stream File.OpenRead(filePath); string hash Convert.ToHexString(sha.ComputeHash(stream)).ToLowerInvariant(); return hash expected.Trim().ToLowerInvariant(); }校验通过后用压缩包里带的 BZip2InputStream 解压更新包。这个类继承自 Stream可以直接 CopyTo 目标文件。因为 WPF 主程序的 exe 正被自己锁着不能边运行边覆盖我一般解压到update子目录然后写一份pending.json记录要替换哪些文件、旧文件备份到哪个目录。3.3.1 替换文件的三个阶段替换不能乱来否则中途断电程序就废了。标准做法就是三个阶段备份、替换、清理。阶段动作失败处理备份把当前 exe/dll 复制到 backup/{version}/失败则停止保留原文件替换把 update 目录内的新文件复制到程序目录失败则从 backup 恢复清理删除 backup 和 update 目录删除失败不影响启动这三个阶段最好放在独立的 Updater.exe 里执行而不是在主进程里。主进程收到 ReadyToRestart 后启动 Updater.exe传入程序目录和 pending.json 路径然后退出自己。Updater 完成替换后再拉起主程序。很多 WPF 项目打包成单文件后也推荐这个方式能绕开“自己替换自己”的文件锁问题。3.4 失败重试的基本参数下载失败要重试但不能是简单的死循环。我通常用指数退避连续失败多次后提示用户检查网络。下面是一组常用默认值参数默认值说明MaxRetryCount3超过后进入失败状态BaseRetryDelay2s第一次重试前等待MaxRetryDelay30s多次失败后最多等待 30sDownloadTimeout30minHttpClient.Timeout 要覆盖慢网场景ProgressReportInterval100ms避免进度事件刷爆 UI 线程如果更新包超过 200MB再考虑断点续传。小体积更新包直接用 GET 下载就好Range 请求还要在服务端和 nginx 上同时支持性价比不高。4. Java 服务端生成更新包与发布配置服务端除了提供接口还要负责把发布产物打成更新包。压缩包里既然带了 BZip2OutputStream.cs压缩格式自然就是 BZip2。我见过不少项目用 ZIP但 WPF 端为了少引第三方包直接用 BZip2 流解压单个文件更省事。如果整个软件有很多 dll、配置文件就先打成 tar 再压缩成 tar.bz2。4.1 用 commons-compress 生成 tar.bz2Java 生成 tar.bz2 不需要自己写位级算法Apache Commons Compress 里已经有 BZip2CompressorOutputStream配合 TarArchiveOutputStream 就能工作。下面是 Maven 依赖和一个小工具方法dependency groupIdorg.apache.commons/groupId artifactIdcommons-compress/artifactId version1.26.2/version /dependencyimport org.apache.commons.compress.compressors.bzip2.BZip2CompressorOutputStream; import org.apache.commons.compress.archivers.tar.TarArchiveEntry; import org.apache.commons.compress.archivers.tar.TarArchiveOutputStream; public static void createTarBz2(Path output, ListPath files) throws IOException { try (TarArchiveOutputStream tar new TarArchiveOutputStream( new BZip2CompressorOutputStream(Files.newOutputStream(output)))) { tar.setLongFileMode(TarArchiveOutputStream.LONGFILE_POSIX); for (Path file : files) { TarArchiveEntry entry new TarArchiveEntry(file.getFileName().toString()); entry.setSize(Files.size(file)); tar.putArchiveEntry(entry); Files.copy(file, tar); tar.closeArchiveEntry(); } } }代码逻辑就是往 tar 流里逐个塞业务文件再由外层 BZip2 压缩整个归档。setLongFileMode 设置为 POSIX是为了处理路径长度超过 100 字符的情况WPF 发布目录如果比较深这个参数踩过坑就会记得。4.2 服务端发布目录与配置更新包生成后放在服务端固定的发布目录里。我的习惯是保留三份历史版本避免误发布后拿不回旧包。目录结构如下/opt/update-server/release/ ├── manifest.json ├── 1.2.0/ │ └── hmiscada-1.2.0.tar.bz2 ├── 1.3.1/ │ └── hmiscada-1.3.1.tar.bz2 └── 1.4.2/ └── hmiscada-1.4.2.tar.bz2manifest.json 放在发布目录根上就是第 2 章那一段 JSON。发布脚本在 Java 服务启动前重新生成一次核心逻辑是遍历目录找最新版本然后调用 sha256sum 生成哈希。这个环节建议自动化我见过手动把哈希填错的案例客户端下载后校验失败用户一直卡在“更新失败”。如果项目里有 mvnw.cmd可以直接用它启动 Spring Boot 服务不用预先装 Maven前提是已把 Java 环境变量配置好。Spring Boot 配置集中在 application.ymlserver: port: 8080 update: root-path: /opt/update-server/release manifest-path: /opt/update-server/release/manifest.json根路径和清单路径拆成两个配置是为了后续支持“多个产品共用发布目录”。如果服务端放在 nginx 后面还要同步调整 client_max_body_size这个参数直接影响客户端下载大更新包时是否被中间层截断。4.3 用 curl 模拟 C# 客户端的完整更新流程服务端写好以后先用命令验证一遍再让 C# 端联调。Windows 和 Linux 都有 curl直接模拟客户端行为最省事。# 模拟客户端上报 1.2.0 版本请求最新清单 curl -s -H X-App-Version: 1.2.0 http://localhost:8080/update/manifest # 根据返回的 downloadUrl 下载更新包 curl -OJ http://localhost:8080/update/packages/hmiscada-1.4.2.tar.bz2 # 校验下载到的文件哈希 sha256sum hmiscada-1.4.2.tar.bz2如果清单里的 downloadUrl 返回 404基本是 Spring Boot 的静态资源映射没配好。使用 FileSystemResource 时重点检查构造函数里传入的 Path 是不是绝对路径。以上流程通过后C# 端下载、校验、解压的调试压力会小很多。5. 自动更新上线前必做的收尾自检、回滚与日志代码写完、接口连通只完成一半。自动更新是典型的“发布时没提示、上线后用户骂”的功能所以最后要落在收尾上。5.1 更新后自检与自动回滚新版本程序不一定能正常启动尤其是配置项变化或依赖缺失的时候。我通常让 Updater.exe 在替换文件后先不直接拉起主程序而是写一个first_run.flag再启动主程序并等待退出码。如果主程序能在启动阶段自检通过并删除这个 flag说明更新成功如果超时或退出码非零就把备份文件拷回来并把日志写到 update.log。下面是一段简化后的批处理逻辑echo off if not exist first_run.flag goto :normal app.exe --self-check if errorlevel 1 ( echo %date% %time% rollback update.log copy /Y backup\app.exe app.exe ) del first_run.flag :normal app.exe这段批处理的关键是 errorlevel 判断。app.exe 的 self-check 参数只做启动级检查比如配置文件是否可加载、关键依赖是否存在。对于 WPF 程序也可以在主程序里写逻辑启动成功后主动删除 flag 文件异常退出时不删让下次启动自动回滚这样更可控。5.2 日志字段要能定位到具体包更新日志不要只记“成功/失败”。每次更新至少应记录 check_time、local_version、remote_version、download_bytes、sha256_ok、rollback 这几个字段。比如一行日志2025-03-14 10:00:12 | 1.2.0 - 1.4.2 | bytes1048576 | sha256ok | rollbackfalse。这行日志放到客户端本地滚动日志里远程排障时能直接看出是下载中断、校验失败还是回滚触发。内网 WPF 上位机场景还可以加一个 HTTP 上报接口把关键字段汇总到服务端不用一台台电脑去看日志。5.3 发布检查清单和最后的技巧如果团队只有一个人维护发布流程最好把检查项写进发布脚本而不是靠脑子记。我每次发完版都会过一遍清单更新包是否用 tarbzip2 重新压缩、sha256 是否与 manifest 一致、minVersion 是否比上一个版本小、Windows 防火墙和杀毒软件是否放行新路径、程序目录是否有写权限、发布包文件名是否只包含字母数字和 -。最后一条是我特别在意的downloadUrl 里的文件名字符集尽量严格限定在[a-zA-Z0-9._-]这样能同时避开 Java 服务端路径穿越、C# 端 Content-Disposition 编码乱码、以及 HTTP 客户端在特殊字符上解析失败三个问题。文件命名干净了自动更新这条链路会在上线后替你省掉不少半夜电话。本文还有配套的精品资源点击获取
简介面向需要持续迭代的WPF桌面程序自动更新是降低分发与维护成本的重要能力。这套代码资源围绕C#客户端与Java服务端完整展示了版本检查、更新包下发、下载解压与替换重启等关键机制适合正在为项目加入自动升级功能、或希望学习跨语言更新架构的开发者。包内共248个文件约45.56MB143个cs文件构成客户端核心逻辑13个xaml提供WPF界面21个java文件负责服务端接口另有exe、jar、msi等可执行/安装产物以及json、xml配置文件与说明文档结构清晰便于定位代码与配置。目前已有172人浏览学习属于中小体量、可直接部署调试的工程示例。深入研读可掌握自动更新中的HTTP/HTTPS通信、版本信息解析、文件校验与压缩替换、进程重启等关键技术借助随包代码和配置能够快速复制到自有C#项目或改造成通用更新组件减少重复搭建成本。1. 自动更新不只是下载一个文件在 WPF 上位机和桌面工具开发中自动更新是典型的“看着容易、做着坑多”。很多人最初打算用 WebClient 把新 exe 下载下来覆盖旧文件运行时才发现exe 被进程占用、版本号比较错误、下载断了一半、新版本启动崩溃却没有回滚。这些问题不是网络问题而是协议和流程没设计好。该压缩包是一套 C# 自动更新客户端和 Java 服务端接口的实现源码里包含 BZip2InputStream.cs、BZip2OutputStream.cs、FileManager.cs、BinaryHandle.cs正好串起压缩、解压、文件覆盖、服务端发布。下面按“协议设计 → C# 客户端 → Java 服务端 → 上线收尾”的顺序拆讲适合要在 WPF 项目里做自动更新的开发者。2. 更新协议设计C# 客户端与 Java 服务端先对齐版本状态自动更新最忌讳两端各写各的。客户端用字符串比较版本号服务端只丢一个文件名过来结果上线前联调半天、上线后依然出问题。我接手这类项目时第一步永远是把“清单”定下来服务端返回结构化数据包含最新版本号和下载文件信息客户端拿到后先做逻辑判断再决定是否下载。2.1 用 JSON 清单替代散装的接口参数在 C# 和 Java 之间传更新信息JSON 是成本最低的方式。WPF 客户端用 System.Text.Json 解析Java 服务端用 Spring Boot 的 Jackson 直接输出几乎不引入额外依赖。相比 XMLJSON 字段更短嵌套结构也更直观。下面是我在项目里常用的更新清单字段约定字段类型含义appNamestring应用标识防止多个产品共用一个服务器时串包versionstring服务端认为的最新版本号minVersionstring允许运行的最低版本低于它时必须强制更新downloadUrlstring更新包相对路径客户端拼接服务器地址sha256string更新包 SHA256下载后逐字节校验releaseNotestring更新说明展示在 WPF 的更新弹窗里协议设计的关键一点是 minVersion。如果客户端版本低于 minVersion不能只做“建议更新”必须阻塞旧版本继续运行否则后续接口升级后老客户端可能连服务器都连不上。对应清单 JSON 示例{ appName: HmiScada, version: 1.4.2, minVersion: 1.2.0, downloadUrl: /packages/hmiscada-1.4.2.bz2, sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08, releaseNote: 修复 Modbus 重连偶发失败的问题 }下载地址如果是相对路径客户端必须根据当前环境切换到 http 或 https。内网 WPF 上位机场景大多用 http外网发布必须强制 https否则更新包在链路上被篡改时哈希校验形同虚设。2.2 C# 端版本判断用 Version 类型而不是字符串比较很多 C# 入门项目会把版本号写成字符串然后直接比较。这种做法在“1.9.2”与“1.10.0”之间会翻车因为字符串按位比较时“1.10.0”反而小于“1.9.2”。正确做法是使用 System.Version。我把检查逻辑拆成一个独立方法方便单元测试public CheckResult ResolveUpdate(UpdateManifest? manifest, Version localVersion) { if (manifest is null) return CheckResult.Failure(服务器没有返回更新清单); var remote Version.TryParse(manifest.Version, out var remoteVersion) ? remoteVersion : throw new FormatException($非法版本号: {manifest.Version}); if (remote localVersion) return CheckResult.NoUpdate; var min Version.TryParse(manifest.MinVersion, out var minVersion) ? minVersion : null; bool forced min is not null localVersion min; return CheckResult.Available(remote, forced); }这段代码里先把服务端版本和本地版本都转成 Version再做三次比较无更新、可选更新、强制更新。CheckResult.Available 里带一个 forced 标志UI 层拿到后弹不同的提示框。如果是强制更新WPF 主窗口就不显示“下次再说”按钮直接进入下载流程。提示如果本地程序有可能从“无版本号”状态升级代码里要把本地版本默认成 0.0避免空引用导致更新功能完全失效。2.3 Java 服务端清单接口和文件下载接口分开服务端不需要做复杂业务核心就是读更新清单返回给客户端再把更新包文件以流的形式交给客户端。我通常写两个接口GET /update/manifest 接收客户端上报的版本返回清单GET /update/packages/{fileName} 返回更新包二进制。分开的原因很实际清单接口要求响应快、可以做灰度策略文件下载需要支持大流量方便单独加 nginx 缓存和带宽限制。RestController RequestMapping(/update) public class UpdateController { private final UpdateManifest currentManifest; private final Path updateRoot; public UpdateController(Value(${update.manifest-path}) String manifestPath, Value(${update.root-path}) String root) throws IOException { this.updateRoot Paths.get(root); this.currentManifest readManifest(Paths.get(manifestPath)); } GetMapping(/manifest) public ResponseEntity? manifest(RequestHeader(value X-App-Version, defaultValue 0.0) String clientVersion) { if (compareVersion(clientVersion, 1.0.0) 0) { return ResponseEntity.status(426).body(currentManifest); } return ResponseEntity.ok(currentManifest); } GetMapping(/packages/{fileName}) public ResponseEntityResource package(PathVariable String fileName) { if (!fileName.matches([a-zA-Z0-9._-])) { return ResponseEntity.badRequest().build(); } Path target updateRoot.resolve(fileName).normalize(); if (!target.startsWith(updateRoot) || !Files.exists(target)) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) .header(Content-Disposition, attachment; filename\ fileName \) .body(new FileSystemResource(target)); } }这里有两个容易在 Java 面试八股文里被问到的点。第一客户端版本过低时返回 426 Upgrade Required而不是硬编码 200客户端可以专门捕获这个状态码做强制更新。第二fileName 直接用 PathVariable 拼路径存在目录穿越风险matches 正则过滤加 normalize 后校验 startsWith是 Java 服务端的标准防御姿势。自动更新接口虽然简单安全边界不能省。整个更新协议到这里就闭环了客户端上报版本服务端回清单客户端比较后决定是否下载下载接口用路径参数定位文件。3. 把 C# WPF 自动更新模块做成独立服务协议定完就轮到客户端落地。很多 WPF MVVM 项目会把自动更新直接写进 MainViewModel然后发现界面等待、进度回调、退出重启全搅在一起。我自己的项目里自动更新更像是一个“可独立启动的模块”接收服务器地址和当前版本号经过检查、下载、校验、准备四个阶段最后通过事件告诉界面层该显示什么。3.1 更新服务和 WPF 界面解耦WPF 上位机里 MVVM 是标配加不加 Prism 都有套路。自动更新代码放 ViewModel字段一多就会和业务状态互相干扰。常见做法是定义 UpdateService构造函数传入 HttpClient 和事件回调public class UpdateService { private readonly HttpClient _http; private readonly Version _localVersion; public UpdateService(HttpClient http, Version localVersion) { _http http; _localVersion localVersion; } public event EventHandlerUpdateProgress? ProgressChanged; public event EventHandlerUpdateState? StateChanged; public async Task RunAsync(CancellationToken ct) { var manifest await GetManifestAsync(ct); var decision ResolveUpdate(manifest, _localVersion); if (decision.Kind UpdateKind.None) return; StateChanged?.Invoke(this, UpdateState.Downloading); var packageFile Path.Combine(Path.GetTempPath(), ${manifest.AppName}-{manifest.Version}.bz2); await DownloadPackageAsync(manifest.DownloadUrl, packageFile, ct); if (!VerifySha256(packageFile, manifest.Sha256)) throw new InvalidDataException(更新包哈希校验失败); PrepareUpdate(packageFile, manifest.Version, ct); StateChanged?.Invoke(this, UpdateState.ReadyToRestart); } }更新服务把流程固化成几个阶段获取清单、版本判断、下载、校验、准备。UI 只需要订阅 StateChanged 事件根据 ReadyToRestart 提示用户是否立即重启。WPF 的 Dispatcher 会在事件回调里自动回到 UI 线程不需要额外写 Invoke前提是事件在 UI 线程的同步上下文里触发。3.2 下载更新包流式下载与进度上报下载最大的坑是直接把整个包 ReadAsByteArrayAsync内存占用和 UI 卡死一起出现。我一般用 ResponseHeadersRead 配合 ReadAsStreamAsync一边从网络读一边写磁盘同时通过事件上报进度。这样能避免更新包过大导致内存暴涨也方便在界面上画进度条。private async Task DownloadPackageAsync(string url, string destFile, CancellationToken ct) { using var response await _http.GetAsync(url, HttpCompletionOption.ResponseHeadersRead, ct); response.EnsureSuccessStatusCode(); await using var source await response.Content.ReadAsStreamAsync(ct); await using var target new FileStream(destFile, FileMode.Create, FileAccess.Write, FileShare.None, 81920, true); var buffer new byte[81920]; int read; long received 0; long total response.Content.Headers.ContentLength ?? 0; while ((read await source.ReadAsync(buffer, ct)) 0) { await target.WriteAsync(buffer.AsMemory(0, read), ct); received read; if (total 0) ProgressChanged?.Invoke(this, new UpdateProgress((int)(received * 100 / total))); } }代码里的 81920 字节缓冲区是 80KB对齐 FileStream 默认缓冲区后能减少用户态和内核态的切换。如果更新包经常在 1MB 以下缓冲区可以降到 4096省内存但吞吐量略低。下载路径建议用 Path.GetTempPath() 组合文件名不要放程序目录避免杀毒软件对写入 exe 目录产生告警。3.3 校验、解压和准备更新更新包下载后要先做哈希校验。服务端生成的 SHA256 不能只在浏览器里看要在 CI 或发布脚本里自动算。这里给出一个简单校验函数private static bool VerifySha256(string filePath, string expected) { using var sha SHA256.Create(); using var stream File.OpenRead(filePath); string hash Convert.ToHexString(sha.ComputeHash(stream)).ToLowerInvariant(); return hash expected.Trim().ToLowerInvariant(); }校验通过后用压缩包里带的 BZip2InputStream 解压更新包。这个类继承自 Stream可以直接 CopyTo 目标文件。因为 WPF 主程序的 exe 正被自己锁着不能边运行边覆盖我一般解压到update子目录然后写一份pending.json记录要替换哪些文件、旧文件备份到哪个目录。3.3.1 替换文件的三个阶段替换不能乱来否则中途断电程序就废了。标准做法就是三个阶段备份、替换、清理。阶段动作失败处理备份把当前 exe/dll 复制到 backup/{version}/失败则停止保留原文件替换把 update 目录内的新文件复制到程序目录失败则从 backup 恢复清理删除 backup 和 update 目录删除失败不影响启动这三个阶段最好放在独立的 Updater.exe 里执行而不是在主进程里。主进程收到 ReadyToRestart 后启动 Updater.exe传入程序目录和 pending.json 路径然后退出自己。Updater 完成替换后再拉起主程序。很多 WPF 项目打包成单文件后也推荐这个方式能绕开“自己替换自己”的文件锁问题。3.4 失败重试的基本参数下载失败要重试但不能是简单的死循环。我通常用指数退避连续失败多次后提示用户检查网络。下面是一组常用默认值参数默认值说明MaxRetryCount3超过后进入失败状态BaseRetryDelay2s第一次重试前等待MaxRetryDelay30s多次失败后最多等待 30sDownloadTimeout30minHttpClient.Timeout 要覆盖慢网场景ProgressReportInterval100ms避免进度事件刷爆 UI 线程如果更新包超过 200MB再考虑断点续传。小体积更新包直接用 GET 下载就好Range 请求还要在服务端和 nginx 上同时支持性价比不高。4. Java 服务端生成更新包与发布配置服务端除了提供接口还要负责把发布产物打成更新包。压缩包里既然带了 BZip2OutputStream.cs压缩格式自然就是 BZip2。我见过不少项目用 ZIP但 WPF 端为了少引第三方包直接用 BZip2 流解压单个文件更省事。如果整个软件有很多 dll、配置文件就先打成 tar 再压缩成 tar.bz2。4.1 用 commons-compress 生成 tar.bz2Java 生成 tar.bz2 不需要自己写位级算法Apache Commons Compress 里已经有 BZip2CompressorOutputStream配合 TarArchiveOutputStream 就能工作。下面是 Maven 依赖和一个小工具方法dependency groupIdorg.apache.commons/groupId artifactIdcommons-compress/artifactId version1.26.2/version /dependencyimport org.apache.commons.compress.compressors.bzip2.BZip2CompressorOutputStream; import org.apache.commons.compress.archivers.tar.TarArchiveEntry; import org.apache.commons.compress.archivers.tar.TarArchiveOutputStream; public static void createTarBz2(Path output, ListPath files) throws IOException { try (TarArchiveOutputStream tar new TarArchiveOutputStream( new BZip2CompressorOutputStream(Files.newOutputStream(output)))) { tar.setLongFileMode(TarArchiveOutputStream.LONGFILE_POSIX); for (Path file : files) { TarArchiveEntry entry new TarArchiveEntry(file.getFileName().toString()); entry.setSize(Files.size(file)); tar.putArchiveEntry(entry); Files.copy(file, tar); tar.closeArchiveEntry(); } } }代码逻辑就是往 tar 流里逐个塞业务文件再由外层 BZip2 压缩整个归档。setLongFileMode 设置为 POSIX是为了处理路径长度超过 100 字符的情况WPF 发布目录如果比较深这个参数踩过坑就会记得。4.2 服务端发布目录与配置更新包生成后放在服务端固定的发布目录里。我的习惯是保留三份历史版本避免误发布后拿不回旧包。目录结构如下/opt/update-server/release/ ├── manifest.json ├── 1.2.0/ │ └── hmiscada-1.2.0.tar.bz2 ├── 1.3.1/ │ └── hmiscada-1.3.1.tar.bz2 └── 1.4.2/ └── hmiscada-1.4.2.tar.bz2manifest.json 放在发布目录根上就是第 2 章那一段 JSON。发布脚本在 Java 服务启动前重新生成一次核心逻辑是遍历目录找最新版本然后调用 sha256sum 生成哈希。这个环节建议自动化我见过手动把哈希填错的案例客户端下载后校验失败用户一直卡在“更新失败”。如果项目里有 mvnw.cmd可以直接用它启动 Spring Boot 服务不用预先装 Maven前提是已把 Java 环境变量配置好。Spring Boot 配置集中在 application.ymlserver: port: 8080 update: root-path: /opt/update-server/release manifest-path: /opt/update-server/release/manifest.json根路径和清单路径拆成两个配置是为了后续支持“多个产品共用发布目录”。如果服务端放在 nginx 后面还要同步调整 client_max_body_size这个参数直接影响客户端下载大更新包时是否被中间层截断。4.3 用 curl 模拟 C# 客户端的完整更新流程服务端写好以后先用命令验证一遍再让 C# 端联调。Windows 和 Linux 都有 curl直接模拟客户端行为最省事。# 模拟客户端上报 1.2.0 版本请求最新清单 curl -s -H X-App-Version: 1.2.0 http://localhost:8080/update/manifest # 根据返回的 downloadUrl 下载更新包 curl -OJ http://localhost:8080/update/packages/hmiscada-1.4.2.tar.bz2 # 校验下载到的文件哈希 sha256sum hmiscada-1.4.2.tar.bz2如果清单里的 downloadUrl 返回 404基本是 Spring Boot 的静态资源映射没配好。使用 FileSystemResource 时重点检查构造函数里传入的 Path 是不是绝对路径。以上流程通过后C# 端下载、校验、解压的调试压力会小很多。5. 自动更新上线前必做的收尾自检、回滚与日志代码写完、接口连通只完成一半。自动更新是典型的“发布时没提示、上线后用户骂”的功能所以最后要落在收尾上。5.1 更新后自检与自动回滚新版本程序不一定能正常启动尤其是配置项变化或依赖缺失的时候。我通常让 Updater.exe 在替换文件后先不直接拉起主程序而是写一个first_run.flag再启动主程序并等待退出码。如果主程序能在启动阶段自检通过并删除这个 flag说明更新成功如果超时或退出码非零就把备份文件拷回来并把日志写到 update.log。下面是一段简化后的批处理逻辑echo off if not exist first_run.flag goto :normal app.exe --self-check if errorlevel 1 ( echo %date% %time% rollback update.log copy /Y backup\app.exe app.exe ) del first_run.flag :normal app.exe这段批处理的关键是 errorlevel 判断。app.exe 的 self-check 参数只做启动级检查比如配置文件是否可加载、关键依赖是否存在。对于 WPF 程序也可以在主程序里写逻辑启动成功后主动删除 flag 文件异常退出时不删让下次启动自动回滚这样更可控。5.2 日志字段要能定位到具体包更新日志不要只记“成功/失败”。每次更新至少应记录 check_time、local_version、remote_version、download_bytes、sha256_ok、rollback 这几个字段。比如一行日志2025-03-14 10:00:12 | 1.2.0 - 1.4.2 | bytes1048576 | sha256ok | rollbackfalse。这行日志放到客户端本地滚动日志里远程排障时能直接看出是下载中断、校验失败还是回滚触发。内网 WPF 上位机场景还可以加一个 HTTP 上报接口把关键字段汇总到服务端不用一台台电脑去看日志。5.3 发布检查清单和最后的技巧如果团队只有一个人维护发布流程最好把检查项写进发布脚本而不是靠脑子记。我每次发完版都会过一遍清单更新包是否用 tarbzip2 重新压缩、sha256 是否与 manifest 一致、minVersion 是否比上一个版本小、Windows 防火墙和杀毒软件是否放行新路径、程序目录是否有写权限、发布包文件名是否只包含字母数字和 -。最后一条是我特别在意的downloadUrl 里的文件名字符集尽量严格限定在[a-zA-Z0-9._-]这样能同时避开 Java 服务端路径穿越、C# 端 Content-Disposition 编码乱码、以及 HTTP 客户端在特殊字符上解析失败三个问题。文件命名干净了自动更新这条链路会在上线后替你省掉不少半夜电话。本文还有配套的精品资源点击获取
