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

其实 Electron 说到底，不过是个普普通通的 Win32 桌面应用罢了，可微软商店它只认 MSIX。这篇文章，就借着我们 HagiCode Desktop 实打实跑通的那套构建配置，把「注册开发者账号 → 打 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-msix maker，它能在打包阶段就直接产出 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": "CN=8B6C8A94-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-latest runner 上不可。这一点是绕不开的硬约束，不像打包那样可以塞进 Linux 容器里去。

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

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

步骤 1：注册开发者账号

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

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

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

// forge.store-config.json
{
  "packageIdentity": {
    "displayName": "Hagicode",
    "publisherDisplayName": "newbe36524",
    "publisher": "CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F",
    "identityName": "newbe36524.Hagicode"
  }
}

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

微软商店要的是一组固定尺寸的 PNG：StoreLogo.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 Name="newbe36524.Hagicode"
          Publisher="CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F"
          Version="1.2.3.0" />

<Applications>
  <Application Id="Hagicode" Executable="Hagicode.exe" EntryPoint="Windows.FullTrustApplication">
    <uap:VisualElements ... />
  </Application>
</Applications>

<!-- 能力声明：runFullTrust 是桌面应用的关键 -->
<Capabilities>
  <rescap:Capability Name="runFullTrust" />
  <Capability Name="internetClientServer" />
</Capabilities>

注意那一行 EntryPoint="Windows.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_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 提交：

# 配置凭证
msstore reconfigure --tenantId $env:AZURE_AD_TENANT_ID `
  --clientId $env:AZURE_AD_APPLICATION_CLIENT_ID `
  --clientSecret $env:AZURE_AD_APPLICATION_SECRET `
  --sellerId $env:SELLER_ID

# 提交 MSIX 包到预留的产品
msstore publish "$packagePath" -id $env:MICROSOFT_STORE_PRODUCT_ID

提交完之后，还要回到 Partner Center 把商店详情（描述、截图、定价、分级）填齐，最后点一下提交审核。审核一般要等 1–3 个工作日，第一次提审嘛，总会久一点。

实践：把配置和踩坑经验沉淀下来

走完一遍流程之后，下面这些实践，能让你少走一些弯路——毕竟弯路走多了，也就不觉得弯了，只是有些事能省则省。

配置文件要分开存

把「通用构建配置」和「商店特定配置」分开存放，是关键。我们的做法是：forge.config.js 跑日常构建（NSIS、portable、macOS dmg），forge.store-config.json 只在商店构建的时候，通过 extends 继承并覆盖：

{
  "extends": "forge.config.js",
  "buildVersion": "0.1.0.0",
  "packageIdentity": { /* 商店预留身份 */ },
  "msix": {
    "minVersion": "10.0.17763.0",
    "maxVersionTested": "10.0.19045.0",
    "capabilities": ["runFullTrust", "internetClient", "internetClientServer", "privateNetworkClientsServer"]
  }
}

这样一来，商店版和发行版，彼此都不会互相污染。HagiCode Desktop 同时维护着三套发行渠道，配置分离，是我们能稳定迭代下去的前提。

版本号必须是四段

MSIX 的版本号必须是 Major.Minor.Build.Revision 四段（比如 1.2.3.0），可 Electron 的 package.json 通常只写三段。那个 buildVersion 字段，就是用来补最后一段的——商店提交的时候，版本号必须递增，第四段非常方便，可以用来区分同一个语义版本下的多次提交。这一点，踩过的人都懂；没踩过的，迟早也会踩。

多语言声明

商店支持多语言的 listing，对应到清单里，就是那一条条 <Resource Language="..." />。我们声明了十种语言，商店会要求每种语言都填上一份描述（可以先用机器翻译过审，再慢慢本地化）。prepare-msix.js 里对应的渲染逻辑是这样：

// 把语言列表渲染成 MSIX 清单里的 Resource 标签
function renderResourceTags(languages) {
  return languages
    .map((language) => `    <Resource Language="${escapeXml(language)}" />`)
    .join('\n');
}

常见坑（重点看）

下面这些坑，HagiCode Desktop 几乎每一个都踩过：

1. Publisher 不匹配：从 Partner Center 复制 publisher 字符串的时候，一不小心就丢了空格或者弄错了大小写，提交直接被拒。建议直接写成配置文件，别手敲。
2. 缺少 runFullTrust：应用启动之后，没法访问文件系统，也拉不起子进程，表现成各种诡异的崩溃，排查起来，可费劲了。
3. 图标尺寸不全：MakeAppx 不校验，可商店审核会打回。prepare-msix.js 提前校验，是个有效的防御。
4. 版本号不递增：商店拒绝接收相同或者更低的版本号，CI 流水线得保证每次构建都 bump。
5. 在非 Windows 环境里跑 maker-msix：会找不到 MakeAppx，必须用 windows-latest runner。
6. 签名混乱：自测用自签证书，商店提交用空签名让微软重签，这两条路径要分开，别把自签证书塞进提交包里去。

自动化建议

第一次手动把全流程走完、每一步都摸清之后，强烈建议接上 GitHub Actions 做自动化。我们最后把版本解析、MSIX 构建、GitHub Release 发布、商店发布串成了一条流水线，每 4 小时检查一次新版本。这部分细节，在我们另一篇文章《Windows 应用自动上架 Microsoft Store 的自动化实践》里有完整的拆解。

如果你只是想先把应用挂上商店、商业化（订阅 / 永久授权）之后再接，也可以看看我们《Electron 桌面应用如何接入 Microsoft Store 订阅与永久许可证》那篇，那篇讲的，是商店上架之后的商业化能力对接。

参考资料

• Microsoft Store CLI 文档
• electron-forge maker-msix
• MSIX 文档
• HagiCode 官网
• HagiCode-org/site GitHub 仓库

总结

围绕“Electron 应用如何上架微软商店：从 MSIX 打包到商店提交”，更稳妥的推进方式是先把关键配置、依赖边界和落地路径逐步跑通，再补齐优化细节。

当目标、步骤和验收点都明确之后，这类方案通常就能更顺畅地进入实际交付。

原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。

• 本文作者: newbe36524
• 原文链接: https://docs.hagicode.com/go?platform=cnblogs&target=%2Fblog%2F2026-06-18-electron-app-publish-to-microsoft-store%2F
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!