手里有这么一个 Electron 应用要在 Windows 上分发给最终用户。除了一直以来都在用的 NSIS 安装包、便携版之外我们还盼着它能出现在微软商店里。说起来原因其实挺现实的可信分发渠道商店里的应用都是签过名、审过的用户安装的时候不会再被 SmartScreen 拦也不必去面对那一句冷冰冰的「未知发行者」。自动更新与商业化更新的事商店替你接管了订阅、永久许可证也都能直接对接上。覆盖 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{name: electron-forge/maker-msix,platforms: [win32],config: {appManifest: msixManifestPath,packageAssets: msixAssetsPath,logLevel: warn,...(windowsKitPath ? { windowsKitPath } : {}),...(windowsKitVersion ? { windowsKitVersion } : {}),...msixSigningConfig,},},关键输入其实就两个appManifest也就是 AppxManifest.xml定义包身份和能力和packageAssets商店图标资产。这两个要是错了后面做得再漂亮也是白搭。2. 包身份必须提前在合作伙伴中心预留MSIX 包里那个Identity字段Name、Publisher可不是随便填填就行的必须和合作伙伴中心里预留的应用身份分毫不差差一个字符都会被打回来。我们预留的身份记在forge.store-config.json里{packageIdentity: {displayName: Hagicode,publisherDisplayName: newbe36524,publisher: CN8B6C8A94-AAE5-4C8B-9202-A29EA42B042F,identityName: newbe36524.Hagicode,backgroundColor: transparent,languages: [en-US, zh-CN, zh-TW, ja-JP, ko-KR, de-DE, fr-FR, es-ES, pt-BR, ru-RU]}}这里头那个publisher字符串是从开发者账号注册之后微软签发的证书主题里来的必须逐字符匹配。identityName呢则是你预留的包名前缀。这个字符串一定要从合作伙伴中心原样复制下来千万别自己手敲——这件事我们在后面「常见坑」里还会再唠一遍。3. 桌面应用必须声明runFullTrust能力Electron 应用要用到完整的文件系统访问、要拉起子进程、还要跑 Node 运行时这些只能在「完全信任」模式下才能实现。所以 MSIX 清单里必须老老实实声明runFullTrust能力不然应用一启动就被沙箱给拦下了表现出来的就是各种让人摸不着头脑的崩溃。我们的配置长这样{msix: {minVersion: 10.0.17763.0,maxVersionTested: 10.0.19045.0,capabilities: [runFullTrust,internetClient,internetClientServer,privateNetworkClientsServer]}}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 证书主题字符串大概长这样CNXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX。这就是后面publisher字段唯一的来源。步骤 2在商店里预留应用身份在合作伙伴中心新建一个应用填上你想保留的名称。系统会分配给你identityName再和你自己的 Publisher 一组合完整的包身份就成型了。把这个身份原样抄到本地配置里// forge.store-config.json{packageIdentity: {displayName: Hagicode,publisherDisplayName: newbe36524,publisher: CN8B6C8A94-AAE5-4C8B-9202-A29EA42B042F,identityName: newbe36524.Hagicode}}步骤 3准备商店图标资产微软商店要的是一组固定尺寸的 PNGStoreLogo.png、Square44x44Logo.png、Square150x150Logo.png、Wide310x150Logo.png之类的。我们的prepare-msix.js脚本在打包之前会先校验这些资产是不是都齐了// 校验商店必需的图标资产缺一个都不行const requiredAssets [StoreLogo.png, Square44x44Logo.png, Square150x150Logo.png, Wide310x150Logo.png];for (const assetName of requiredAssets) {const assetPath path.join(paths.generatedAssetsPath, assetName);if (!fs.existsSync(assetPath)) {throw new Error(Missing required MSIX asset after preparation: ${assetPath});}}为什么要这么做呢因为缺一个尺寸MakeAppx 打包的时候并不会告诉你具体哪里错了等到商店审核的时候才被打回来——这时候你已经等了好几天了。提前校验是一个非常有效的防御。步骤 4生成 AppxManifest.xml清单里要塞进包身份、能力、可视资产、入口可执行文件。我们用一个覆盖配置forge.store-config.json来驱动prepare-msix.js生成清单确保身份和商店对得上。清单里关键的那几段大概是这样!-- 包身份必须和合作伙伴中心一致 --Identity Namenewbe36524.HagicodePublisherCN8B6C8A94-AAE5-4C8B-9202-A29EA42B042FVersion1.2.3.0 /ApplicationsApplication IdHagicode ExecutableHagicode.exe EntryPointWindows.FullTrustApplicationuap:VisualElements ... //Application/Applications!-- 能力声明runFullTrust 是桌面应用的关键 --Capabilitiesrescap:Capability NamerunFullTrust /Capability NameinternetClientServer //Capabilities注意那一行EntryPointWindows.FullTrustApplication这可是桌面应用的关键标记配合runFullTrust能力才能以完整的权限跑起来。少了它应用就只能乖乖待在沙箱里憋屈得很。步骤 5用 maker-msix 打包构建命令写在package.json里{scripts: {build:win:store: npm run generate:store-bindings node scripts/build-store-package.js}}它最终调起 Electron Forge把forge.store-config.json当作覆盖配置带进去maker-msix 会去调用 Windows SDK 的MakeAppx吐出.msix文件来。这里头有个硬约束打包必须在 Windows 上做或者带 Windows SDK 的容器里毕竟它依赖MakeAppx这点没法绕。步骤 6签名商店提交时可以不签这一步其实很容易被忽略——提交到商店的包微软会用它自己的证书重新签一遍所以「正式提交」之外的开发自测阶段是可以不签名的。只是你要是想在本地装上测试一下那就得用受信任证书签一下了不然 Windows 是会拒绝安装的。我们的resolveMsixSigningConfig在没配签名材料的时候会返回一个空对象让流程接着往下走// 没配签名材料就不签让商店统一重签function resolveMsixSigningConfig() {if (!process.env.MSIX_CERT_FILE) return {};return {signMethod: signtool,certFilePath: process.env.MSIX_CERT_FILE,certPassword: process.env.MSIX_CERT_PASSWORD,};}把「自测签名」和「提交空签名」这两条路径分开是一个非常关键的实践。步骤 7配置 Microsoft Store CLI 凭证到 Azure 门户去创建一个 Azure AD 应用给它授予访问 Partner Center 的权限然后拿到下面这一组凭证AZURE_AD_APPLICATION_CLIENT_IDAZURE_AD_APPLICATION_SECRETAZURE_AD_TENANT_IDSELLER_ID合作伙伴中心的卖家 IDMICROSOFT_STORE_PRODUCT_ID预留应用的产品 ID这一步稍微有点绕不过 Azure 门户和 Partner Center 的文档里都写得很细照着做就是了。步骤 8提交到商店在 Windows 环境里用 Microsoft Store CLI 提交
