Documentation Index
Fetch the complete documentation index at: https://docs.superun.com/llms.txt
Use this file to discover all available pages before exploring further.
微信小程序是什么
微信小程序是腾讯在微信生态内提供的一种轻量应用形态。它具备这些核心特征：- 即用即走：用户无需在应用商店下载安装，扫码或搜索后直接使用
- 跑在微信原生容器里：和普通 H5（跑在 WebView 里）不同，小程序运行在微信原生容器中，可以调用
wx.*系列原生 API - 依托微信关系链分发：可以通过分享、扫码、附近的小程序等方式快速触达用户
使用须知
- 当前方案使用小程序 web-view 组件，微信限制个人类型小程序不支持 web-view，仅企业主体小程序可用。
接入前的必要配置
在 superun 启用微信小程序插件之前，你需要先在 微信公众平台 准备好下面三件配置：| 配置项 | 文件 / 形态 | 用途 | 在哪里拿 |
|---|---|---|---|
| AppID | 18 位字符串 | 小程序唯一身份，绑定 superun 项目时填入 | 微信公众平台 → 开发管理 → 开发设置 → 开发者 ID |
| 小程序代码上传密钥（.pem 私钥） | private.{appid}.key（PEM 格式 RSA 私钥） | superun 代你把小程序代码包上传到微信，进行预览/审核 | 微信公众平台 → 开发管理 → 开发设置 → 小程序代码上传 |
| 业务域名校验文件 | MP_verify_xxxx.txt | 让微信确认你拥有该 H5 域名，配置后才能在小程序里通过 <web-view> 加载你的 H5 | 微信公众平台 → 开发管理 → 开发设置 → 业务域名 |
- AppID 解决「这是哪个小程序」——所有上传、登录、支付等操作都基于这个 ID
- 上传密钥解决「代码怎么上去」——superun 用它代表你的身份，把代码包推送到微信
- 业务域名校验文件解决「H5 怎么被允许在小程序里展示」——微信只允许已认领域名的页面在
<web-view>中打开
分段获取流程
1. 获取 AppID
前置准备：- 已在微信公众平台注册账号，类型为「小程序」
- 已完成主体信息登记（个人或企业，两种主体都能拿到 AppID，但可用能力会有差异）
- 打开 微信公众平台 并使用管理员账号登录
- 左侧菜单进入「开发管理」
- 顶部切换到「开发设置」选项卡
- 滚动到「开发者 ID」分块，复制 AppID（小程序 ID）
2. 获取代码上传密钥（.pem 密钥）
前置准备：- 已确认本人是该小程序的「管理员」（普通运营者无权下载上传密钥）
- 在「开发管理 → 开发设置」页面继续向下滚动，找到「小程序代码上传」分块
- 如果是首次使用，点击「生成」；如果之前生成过、本地已经丢失，可以「重置」（重置会让旧密钥立即失效）
- 浏览器会自动下载一个文件，文件名形如
private.{appid}.key，这就是你需要的代码上传密钥 - 用记事本/文本编辑器打开它，可以看到
-----BEGIN RSA PRIVATE KEY-----开头——这是标准的 PEM 格式 RSA 私钥
40164 错误。
请在 superun 小程序插件配置页查看最新的出口 IP 列表，复制后粘贴到微信公众平台。格式示例：
以上为示例格式，实际 IP 请以 superun 产品内展示的为准。
3. 获取并部署业务域名校验文件
操作路径：- 在「开发管理 → 开发设置」页面滚动到「业务域名」分块
- 点击「修改」（首次配置点「开始配置」）
- 在弹出的浮层里，按提示先点击「下载校验文件」按钮，浏览器会下载一个文件，文件名形如
MP_verify_AbCdEf123456.txt - 把这个文件放到你 H5 站点的根目录——也就是要让
https://你的域名/MP_verify_AbCdEf123456.txt这个 URL 能被直接访问到，返回文件内容 - 回到浮层里，在域名输入框中填入业务域名，仅填 host，不带协议、不带路径，例如
my-app.superun.com - 点击「保存」，微信会立即去 GET 上一步那个 URL 做校验，校验通过后业务域名生效
这里填写的域名，可以在 superun 的小程序配置页直接看到推荐的填写值，复制粘贴到微信后台即可。
三项配置如何串起来
下面这张图把三件配置之间的依赖关系拉成一条线，可以对照检查每一步是否完成：预览/上传必要配置
在 superun 后台触发「预览」或「上传」之前，必须先在微信公众平台完成两类白名单配置；任一缺失都会导致整个流程在微信侧被直接拦截。| 配置项 | 用于哪个动作 | 不配置的后果 | 配置入口 |
|---|---|---|---|
| IP 白名单 | 代码上传（superun 服务器调用微信 CI 接口） | 上传被拒，返回错误码 40164 | 开发管理 → 开发设置 → 小程序代码上传 → IP 白名单 |
| 业务域名 | 预览 / 线上运行（小程序 <web-view> 加载 H5） | 预览扫码后 <web-view> 打开空白页，提示「不在以下 业务域名 列表中」 | 开发管理 → 开发设置 → 业务域名 |
为什么需要分别配置这两件事
预览/上传其实是两条独立链路，微信用不同的字段来做身份校验：- 上传链路：流量是
superun 服务器 → 微信开放接口，微信校验「来源 IP」是否被授权，因此要把 superun 的服务器出口 IP 加入 IP 白名单 - 预览/运行链路：流量是
微信客户端 → 你的 H5 域名，微信校验「目标域名 host」是否被授权，因此要把 H5 域名加入业务域名
校验流程
操作要点
- IP 白名单：将 superun 小程序插件配置页展示的出口 IP 全部加入「小程序代码上传 → IP 白名单」，详细步骤见 2. 获取代码上传密钥（.pem 密钥） 中「配套：IP 白名单」一节
- 业务域名：将 H5 站点 host（仅 host，不带协议/路径）加入「业务域名」，并在配置前把校验文件部署到该域名根目录，详细步骤见 3. 获取并部署业务域名校验文件
在 superun 内一键预览 / 上传
完成上述配置后，你无需打开微信开发者工具即可在 superun 内完成代码包预览与上传：- 一键预览：在微信小程序插件详情页点击「预览」，superun 会构建小程序代码包并直接生成预览二维码，用微信扫码即可在手机上体验
- 一键上传：点击「上传」，superun 会把代码包推送到微信公众平台后台，无需再切换到微信开发者工具；上传完成后可在微信公众平台「版本管理」中提交审核或体验
- 配置表单 UX 升级：插件详情页表单交互全面优化，关键字段（AppID / 上传密钥 / 业务域名）的填写与校验提示更清晰
- 移动端预览入口：在移动端预览入口的位置与交互调整为更易触达的位置，预览体验更顺畅
预览与上传的具体按钮文案、位置以你当前产品版本为准。
业务域名填写失败排查
如果你在公众平台「业务域名」点保存时遇到「文件校验失败」或「系统错误，请稍后再试」，绝大多数原因都是：微信服务器拿不到根路径上「正确的」校验文件内容。可以按以下顺序自查（参考 微信官方校验文件检查失败自查指引（2025 版））。重点检查项
- 文件位置：必须保证从公网根路径能直接访问到，URL 形如
https://你的域名/MP_verify_xxx.txt，不要带任何子路径 - 文件原样：文件名、大小写、扩展名都不能改；文件内容要是微信下载下来的随机字符串，不要被 BOM/换行/HTML 包裹
- SPA 路由：前端框架（Vue/React 等）静态托管时，要在路由配置/nginx 里把
MP_verify_*.txt排除在 SPA fallback 之外 - HTTPS 与 TLS：校验文件所在服务器必须支持 HTTPS，且 SSL 证书未过期；微信校验服务要求服务器允许 TLS 1.1 或「可降级的 TLS 1.2」加密套件，仅支持 TLS 1.3 会校验失败
- 响应耗时：微信对校验请求有秒级超时限制，建议确保该 URL 响应耗时小于 1 秒，避免冷启动函数/慢路由