C# ClickOnce发布与更新教程

ClickOnce是最轻量的Windows桌面应用自动更新方案，依赖Application Files清单、setup.exe引导和.application启动文件协同工作，需正确配置PublishUrl、InstallUrl、ApplicationVersion、SupportUrl等4个关键属性，并确保签名证书有效且一致，否则将出现验证失败或更新静默错误。

ClickOnce 是 Windows 桌面应用最轻量的自动更新方案，但它的发布逻辑和传统安装包完全不同——它不写注册表、不依赖 MSI，而是靠 Application Files 清单 + setup.exe 引导 + .application 启动文件协同工作。一旦路径、签名或更新策略配错，用户就会遇到“无法验证应用程序”“找不到应用程序清单”或“更新失败但无提示”等静默问题。

发布前必须配置的 4 个关键项目属性

右键项目 → “属性” → “发布”选项卡只是入口，真正起作用的是底层 MSBuild 属性。这些值会直接生成 app.publish\MyApp.application 和部署清单中的 URL、版本、签名信息：

• PublishUrl：必须是完整路径（如 \\server\share\ 或 https://example.com/app/），不能是相对路径；本地测试用 file:// 协议需确保目标机器能访问该路径
• InstallUrl：如果和 PublishUrl 不同（例如 CDN 分发），必须显式设置，否则更新时仍回退到 PublishUrl
• ApplicationVersion：格式为 X.Y.Z.W，每次发布必须递增，否则 ClickOnce 认为“无新版本”；建议在 CI 中用构建号自动填充
• SupportUrl 和 ProductName：虽非强制，但缺失会导致用户右键“卸载程序”里显示空名称或跳转 404

签名失效是更新失败的第一大原因

从 .NET 6 开始，Visual Studio 默认不再自动生成测试证书，而 ClickOnce 要求所有部署清单（MyApp.application）和应用清单（Application Files\MyApp_1_0_0_0\MyApp.exe.manifest）都必须用同一张有效证书签名，否则启动时弹出“无法验证应用程序”并终止。

• 用 mage.exe -sign 手动重签前，先确认证书没过期、私钥可访问、且导入到了“当前用户\个人”证书存储中
• 若用通配符证书（如 *.company.com），需确保 PublishUrl 域名匹配，否则签名验证失败
• 开发机重装系统后，原测试证书丢失 → 必须重新生成并更新所有已发布的清单，否则旧用户无法更新

用户端更新行为完全由发布设置控制，不是代码决定的

是否自动检查更新、是否强制重启、更新失败是否静默，全部取决于发布向导最后一步的勾选项，它们会写入 MyApp.application 的 <deployment> 节点，和你的 C# 代码无关：

• 勾选“应用程序应检查更新” → 生成 <subscription><update><expiration maximumAge="0" unit="days"/></update></subscription>，每次启动都查
• 不勾选 → 完全不检查，除非调用 ApplicationDeployment.CurrentDeployment.CheckForUpdateAsync() 手动触发
• “更新后要求用户重启应用程序”被禁用 → 即使有新版本，也会继续运行旧副本，直到下次手动重启
• “指定更新位置”留空 → 更新时仍使用原始 PublishUrl，哪怕你已把新包挪到别处

调试更新失败：看日志比猜更有效

用户点击 setup.exe 或双击 MyApp.application 失败时，Windows 不报详细错误，但日志全在本地：

• 日志路径固定为：%localappdata%\Apps\2.0\DeploymentLog.txt（注意是 DeploymentLog.txt，不是 Application Log）
• 常见错误码：ERROR_COULD_NOT_PARSE_APPLICATION_MANIFEST 说明清单 XML 格式损坏或签名无效；ERROR_NO_MORE_ITEMS 往往是网络权限拦截了对 PublishUrl 的 HTTP HEAD 请求
• 用 mage -verify MyApp.application 可在发布机提前验证签名和结构，避免把坏包推上线

ClickOnce 看似简单，但它的脆弱性藏在路径一致性、证书生命周期和清单嵌套签名里——改一个 URL、换一台发布机、升级一次 VS，都可能让整条更新链断裂。最稳妥的做法是：每次发布后，用一台干净 Win10/11 虚拟机，清空 %localappdata%\Apps，再从头安装并触发一次更新，确认日志里没有 ERROR 行。