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