Electron 应用如何上架微软商店：从 MSIX 打包到商店提交

手里有这么一个 Electron 应用，要在 Windows 上分发给最终用户。除了一直以来都在用的 NSIS 安装包、便携版之外，我们还盼着它能出现在微软商店里。说起来原因其实挺现实的：

1. 可信分发渠道：商店里的应用都是签过名、审过的，用户安装的时候不会再被 SmartScreen 拦，也不必去面对那一句冷冰冰的「未知发行者」。
2. 自动更新与商业化：更新的事，商店替你接管了；订阅、永久许可证，也都能直接对接上。
3. 覆盖 Windows 10/11 自带的入口：winget、商店搜索、开始菜单推荐……这些入口，对拉新是实打实有用的。

只是 Electron 它终究不是 UWP。要想上架微软商店，其实核心也就一件事——把 Electron 的产物重新打包成微软商店认得下的MSIX 包，再老老实实把注册、提交流程走完。听起来轻巧，可真上手了，坑还不少。为了把这些坑填平，我们花了不少功夫把整条链路摸了个通透，下面就把每一步掰开来揉碎了讲。

关于 HagiCode

这篇文章里讲的方案，来自我们在 HagiCode 项目里的实践。HagiCode Desktop 是一个基于 Electron 的桌面端，要同时通过官网、GitHub Release、还有微软商店这三个渠道分发给用户。商店这条渠道是怎么打通的，就是这篇文章要讲的事。文末有更多关于 HagiCode 的信息，要是你感兴趣，不妨拉到底看看。

分析：上架之前必须想清楚的四个问题

上架微软商店这件事，技术链条上有四个关键判断。想清楚了，后面也就不必反复返工了——毕竟谁也不想返工呢。

1. 微软商店只接受 MSIX / AppX，不接受传统 NSIS/EXE

微软商店对桌面应用（Desktop Bridge）的支持，是建立在 MSIX 格式之上的。传统的 NSIS 安装包没法直接提交，得先用MakeAppx重新打包成 MSIX。好在 Electron Forge 提供了一个@electron-forge/maker-msixmaker，它能在打包阶段就直接产出 MSIX，省下了从已安装目录反推打包那一通折腾。

我们项目里就挂着这么一个 maker：

关键输入其实就两个：appManifest（也就是 AppxManifest.xml，定义包身份和能力）和packageAssets（商店图标资产）。这两个要是错了，后面做得再漂亮，也是白搭。

2. 包身份必须提前在合作伙伴中心预留

MSIX 包里那个Identity字段（Name、Publisher），可不是随便填填就行的，必须和合作伙伴中心里预留的应用身份分毫不差，差一个字符都会被打回来。我们预留的身份，记在forge.store-config.json里：

这里头那个publisher字符串，是从开发者账号注册之后微软签发的证书主题里来的，必须逐字符匹配。identityName呢，则是你预留的包名前缀。这个字符串，一定要从合作伙伴中心原样复制下来，千万别自己手敲——这件事我们在后面「常见坑」里还会再唠一遍。

3. 桌面应用必须声明runFullTrust能力

Electron 应用要用到完整的文件系统访问、要拉起子进程、还要跑 Node 运行时，这些只能在「完全信任」模式下才能实现。所以 MSIX 清单里，必须老老实实声明runFullTrust能力，不然应用一启动，就被沙箱给拦下了，表现出来的，就是各种让人摸不着头脑的崩溃。我们的配置长这样：

runFullTrust是桌面应用上架的标配。minVersion设到 17763（也就是 Windows 10 1809），是因为从这个版本起，MSIX 才稳定支持桌面 Win32 应用，设低了，用户装不上；设高了，又覆盖不到那些上了年纪的老机器。

4. 商店提交需要 Windows 环境 + Microsoft Store CLI

打包这件事，倒是可以在跨平台的 CI 上做，可商店提交（msstore publish）就不行了，必须在 Windows 环境里跑 Microsoft Store CLI，还得配好 Azure AD 应用凭证。这也就是为什么自动化流水线里那个publish_store作业，非得跑在windows-latestrunner 上不可。这一点是绕不开的硬约束，不像打包那样可以塞进 Linux 容器里去。

解决：完整上架的八步流程

把上面的分析串起来，要把一个 Electron 应用上架到微软商店，完整的步骤大概是这样的。

步骤 1：注册开发者账号

先到 Partner Center 注册一个开发者账号（个人或者公司都行），把那笔一次性的费用给交了。账号激活之后，你会拿到一个Publisher 证书主题字符串，大概长这样：CN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX。这，就是后面publisher字段唯一的来源。

步骤 2：在商店里预留应用身份

在合作伙伴中心新建一个应用，填上你想保留的名称。系统会分配给你identityName，再和你自己的 Publisher 一组合，完整的包身份就成型了。把这个身份，原样抄到本地配置里：

步骤 3：准备商店图标资产

微软商店要的是一组固定尺寸的 PNG：StoreLogo.png、Square44x44Logo.png、Square150x150Logo.png、Wide310x150Logo.png之类的。我们的prepare-msix.js脚本，在打包之前会先校验这些资产是不是都齐了：

为什么要这么做呢？因为缺一个尺寸，MakeAppx 打包的时候并不会告诉你具体哪里错了，等到商店审核的时候才被打回来——这时候，你已经等了好几天了。提前校验，是一个非常有效的防御。

步骤 4：生成 AppxManifest.xml

清单里要塞进包身份、能力、可视资产、入口可执行文件。我们用一个覆盖配置（forge.store-config.json）来驱动prepare-msix.js生成清单，确保身份和商店对得上。清单里关键的那几段，大概是这样：

注意那一行EntryPoint="Windows.FullTrustApplication"，这可是桌面应用的关键标记，配合runFullTrust能力，才能以完整的权限跑起来。少了它，应用就只能乖乖待在沙箱里，憋屈得很。

步骤 5：用 maker-msix 打包

构建命令写在package.json里：

它最终调起 Electron Forge，把forge.store-config.json当作覆盖配置带进去，maker-msix 会去调用 Windows SDK 的MakeAppx，吐出.msix文件来。这里头有个硬约束：打包必须在 Windows 上做（或者带 Windows SDK 的容器里），毕竟它依赖MakeAppx，这点没法绕。

步骤 6：签名（商店提交时可以不签）

这一步，其实很容易被忽略——提交到商店的包，微软会用它自己的证书重新签一遍，所以「正式提交」之外的开发自测阶段，是可以不签名的。只是你要是想在本地装上测试一下，那就得用受信任证书签一下了，不然 Windows 是会拒绝安装的。我们的resolveMsixSigningConfig在没配签名材料的时候，会返回一个空对象，让流程接着往下走：

把「自测签名」和「提交空签名」这两条路径分开，是一个非常关键的实践。

步骤 7：配置 Microsoft Store CLI 凭证

到 Azure 门户去创建一个 Azure AD 应用，给它授予访问 Partner Center 的权限，然后拿到下面这一组凭证：

• AZURE_AD_APPLICATION_CLIENT_ID
• AZURE_AD_APPLICATION_SECRET
• AZURE_AD_TENANT_ID
• SELLER_ID（合作伙伴中心的卖家 ID）
• MICROSOFT_STORE_PRODUCT_ID（预留应用的产品 ID）

这一步稍微有点绕，不过 Azure 门户和 Partner Center 的文档里都写得很细，照着做就是了。

步骤 8：提交到商店

在 Windows 环境里，用 Microsoft Store CLI 提交：