构建工具

平台只接收 Frozen Package Format v1 .cmpkg。工具把源码或 H5 编译产物转换为运行包；服务端校验和治理制品，不转换 WXML、WXSS 和 JavaScript。工具源码包名称为 community-miniapp-tool，当前版本 0.1.0。开始前准备源码工作副本和对应环境的制品加密配置。

获取与环境准备

受邀 Test 开发者使用团队提供的工具源码或安装版本。公开下载与安装版本说明集中列在环境与兼容。

源码方式要求 Node.js 18 或以上、系统 zip 命令及锁文件中的依赖。在可写的工具副本中运行 npm ci；构建需要 Vue 的生产运行时。GUI 使用 npm run desktop，只启动本地工具服务使用 node bin/miniapp.js serve --host 127.0.0.1 --port 8787。桌面应用另外需要 Electron。外部 Vue/React/uni-app 项目还须准备自己的依赖及 H5 构建脚本。

选择源码类型

输入项目	识别材料	构建方式与限制
Community 小程序	`miniapp.json`，HTML/JS/CSS 页面	打包页面、资源、Vue 与 Community 运行时；使用工具支持的组件和语法
微信原生小程序	`app.json`、`app.js` 或 `project.config.json`	转换页面和 WXML/WXSS，生成 HTML 与 `wx` 适配层；不是完整微信运行时，方法缺口见双端 SDK 接入
uni-app	`manifest.json`、`pages.json`	使用本地 `uni build -p h5 --mode production`，或项目的 H5 构建脚本/已有 H5 输出；不编译 nvue、App 原生插件或微信专属产物
Vue / React / 普通 Web	项目配置、构建脚本及 `index.html`	打包 H5 输出；运行项目自己的 dev server 与产出可上传运行包是不同步骤
Node.js / Midway 等后端	后端项目或 Web 服务	工具识别/编辑项目不等于可打包；服务端程序不能随包运行，须使用配套前端产物

外部 H5 构建优先检查已有输出是否新鲜；需重建时依次选择本地 uni CLI，或 build:h5、build:web、build 脚本，输出目录须包含 index.html。未提供可用编译器/脚本时先在原工具生成 H5，再导入。不能把微信开发者工具的上传命令当作本工具命令。

桌面导入与构建

在项目工作副本上操作；点击“导入”，选择项目根目录，点击“检测项目类型”，确认后“导入并打开”。工具会生成 miniapp.json；微信原生项目还会写入生成页面及运行时文件，外部项目构建可能重建 H5 输出。
核对 miniapp.json 的 id 为平台分配的真实 AppID，version 为本次准备上传的版本；导入时自动生成的 ID 不能代替平台 AppID。检查页面入口、实际使用的权限、域名及兼容条件。
用“运行”检查渲染与业务页面。浏览器预览没有完整原生宿主，登录可能返回模拟值或失败，不能用于确认真实登录、授权、支付及设备能力。
桌面“构建运行包”按钮要求先登录开发者账号。构建后保存实际输出的 .cmpkg 和 SHA-256；CLI 构建方法见下节。
在开发者中心创建版本并上传该 .cmpkg，按体验、审核与发布完成后续操作。工具登录或自动上传失败时，可在开发者中心上传已生成的运行包。

源码 CLI 示例

以下用于新建 Community 示例项目；已有微信/uni-app 项目先按上面的导入流程登记。TOOL_DIR 是已准备依赖的工具工作副本，WORKSPACE_DIR 是独立可写目录，APP_ID 须替换为本应用真实值。CLI 提供 init、list、build、serve 和 doctor；导入已有项目使用桌面入口。

TOOL_DIR=/path/to/community-miniapp-tool
WORKSPACE_DIR=/path/to/miniapp-workspace
APP_ID=miniapp_example

cd "$TOOL_DIR"
node bin/miniapp.js init hello-mini --id "$APP_ID" \
  --title "联调示例" --version 0.1.0 --workspace "$WORKSPACE_DIR"
node bin/miniapp.js list --workspace "$WORKSPACE_DIR"

先检查新项目的 miniapp.json，按真实业务调整默认页面、权限和兼容条件。模板默认包含用户资料权限，不能据此忽略隐私声明。确认后构建：

node bin/miniapp.js build "$APP_ID" --workspace "$WORKSPACE_DIR"

输出在工具目录的 dist/<name>-<version>.cmpkg，文件名优先使用项目 name，不一定使用 AppID；以命令实际打印的路径为准。旁边的解包构建目录仅用于检查，中间 ZIP 构建后删除，不作为上传制品。命令生成运行包，不自动创建平台版本、审核、签名或发布。

当前 CLI 保留本地默认制品加密配置，也接受 COMMUNITY_MINIAPP_PACKAGE_KEY 环境变量；覆盖前确认平台与宿主使用同一环境配置，密钥通过受保护配置注入，不放进命令参数或日志。它用于制品加密，与 AppSecret、支付请求私钥和平台发布签名不同；本地默认不代表 Production 配置已获准。

上传前核对产物

材料或字段	核对方式
`.cmpkg`	保存实际文件大小与 SHA-256；不能将普通 ZIP 改扩展名上传
`appId`、`version`	容器和 `package-manifest.json` 必须一致，并匹配控制台应用及版本
`entry`、`pages`	对应包内实际 HTML；外部 H5 当前只生成 `index.html` 页面清单，不代表业务路由已获得平台页面元数据支持
`permissions`	核对实际调用；当前自动扫描补充用户资料和手机号，不能自动覆盖全部定位、相册、扫码及扩展能力，其他声明须按实际业务核对
`minHostVersion`、`sdkVersion`	工具缺省写入 `1.0.0`；填写该运行包所需的实际最低版本；工具默认值不是已确认的设备支持范围
`apiDomains`、`imageDomains`	工具合并配置及扫描结果；核对纯 HTTPS Origin，同时按应用级服务器域名配置当前控制台
`runtime`、`files`	工具生成运行时引用、文件大小及 SHA-256；文件、页面、权限或运行时变化后重新构建，不能修改加密包或已签名清单

平台包大小上限为 30 MiB，解压后总大小上限 150 MiB，目录及文件条目总数上限 5000，压缩比上限 30。上传校验通过后仍须满足当前审核、隐私及能力条件；平台签名发生在独立审核批准后。各端安装与方法支持见双端 SDK 接入。

常见失败

现象	处理
缺少 Vue 或 `zip`	执行 `npm ci`，安装系统 `zip` 后重试
找不到项目	核对 AppID 与 `--workspace`；已有项目先在桌面导入
外部 H5 无法构建	在原项目安装依赖，确认 H5 构建脚本和含 `index.html` 的输出目录
Community 构建后出现 import 语法错误	保留模板运行时 import 的结尾分号，重新构建；参考示例
包上传字段校验失败	根据返回字段检查清单和项目配置，重新构建
桌面预览登录或原生功能失败	转到宿主体验版验证，检查方法支持

下一步

首次使用可直接运行第一个小程序。得到 .cmpkg 后前往体验、审核与发布；接入原生能力时查阅运行时与双端 SDK。

构建工具 ​

获取与环境准备 ​

选择源码类型 ​

桌面导入与构建 ​

源码 CLI 示例 ​

上传前核对产物 ​

常见失败 ​

下一步 ​