第一个小程序

创建一个点击计数页面，预览后构建 .cmpkg。示例使用工具自带的 Community 项目模板，不调用登录、手机号或支付。

开始前准备

• 按工具环境准备安装 Node.js 18 或以上、zip 和工具依赖。
• 准备可写的工具副本和项目目录。
• 已有应用时使用真实 AppID；只做离线示例可先使用 miniapp_example，上传前替换为控制台 AppID 并重新构建。

1. 创建项目

以下命令中的两个目录由你选择，示例使用独立工作目录：

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 "你好，MetaEco" --version 0.1.0 --workspace "$WORKSPACE_DIR"
node bin/miniapp.js list --workspace "$WORKSPACE_DIR"

命令输出 Created <AppID> at <项目目录>；list 中能看到相同 AppID 和 0.1.0。主要文件如下：

miniapp-workspace/
└── miniapp_example/
    ├── miniapp.json          # AppID、版本、入口和权限
    ├── main.js              # 模板的应用入口辅助代码
    ├── app.css              # 应用样式
    └── pages/index/
        ├── index.html       # 页面容器
        ├── index.js         # 页面逻辑
        └── index.css        # 页面样式

目录名随 APP_ID 变化。保留模板生成的 HTML 和 CSS。

2. 编写页面

将项目的 pages/index/index.js 替换为：

import { definePage, mountCommunityApp, ref } from '/vendor/community-mini.esm.js';

const App = definePage({
  setup() {
    const count = ref(0)
    const message = ref('已点击 0 次')
    function increment() {
      count.value += 1
      message.value = `已点击 ${count.value} 次`
    }
    return { message, increment }
  },
  templateUI: {
    tag: 'c-page',
    props: { title: '你好，MetaEco', subtitle: '第一个小程序' },
    children: [{
      tag: 'c-view',
      props: { title: '点击计数' },
      children: [
        { tag: 'c-pre', text: '$message' },
        { tag: 'c-button', text: '增加一次', on: { tap: 'increment' } }
      ]
    }]
  }
})

mountCommunityApp(App)

Community 项目的运行时 import 语句保留结尾分号，当前打包转换依赖该格式。

ref 保存页面状态，tap 绑定按钮事件，$message 将状态显示到组件中。此文件使用 Community API；微信原生项目的 Page、WXML 和 wx 用法见运行时与双端 SDK。

3. 核对项目配置

打开生成的 miniapp.json，保留 AppID、版本和页面入口，把 permissions 改为 []。默认模板含用户资料示例权限；本页已替换该示例，点击计数无需资料授权。

应核对的字段如下，其余模板字段可保留：

{
  "id": "miniapp_example",
  "name": "hello-mini",
  "version": "0.1.0",
  "entry": "pages/index/index.html",
  "pages": ["pages/index/index.html"],
  "permissions": []
}

id 使用本项目真实值。后续增加网络、定位或其他能力时，根据实际调用调整权限、域名及隐私声明。

4. 预览与构建

从工具目录启动本地服务：

node bin/miniapp.js serve --host 127.0.0.1 --port 8787 \
  --workspace "$WORKSPACE_DIR"

打开命令输出的本地地址，选择项目并点击“运行”。页面应显示“已点击 0 次”，点击“增加一次”后数字递增。预览不需要真实登录码。

另开终端，设置同样的 TOOL_DIR、WORKSPACE_DIR 和 APP_ID 后构建：

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

预期结果： 命令打印 Built <AppID> 0.1.0 和输出路径，工具的 dist/ 下生成 hello-mini-0.1.0.cmpkg。旁边的构建目录用于检查文件；上传时选择 .cmpkg。

常见失败

现象	处理
App already exists	改用新项目 AppID，或编辑已创建项目；不要覆盖需要保留的源码
找不到 zip 或 Vue 运行时	检查系统 zip，在工具副本中执行 npm ci
list 中没有项目	确认各命令使用相同 --workspace
预览数字不变化	核对页面逻辑文件，刷新项目预览并查看页面错误
上传提示 AppID 或版本不符	使用控制台分配的 AppID 和创建的版本重新构建

下一步

按体验、审核与发布上传运行包。即使示例不处理个人信息，也需要提交实际的不处理个人信息声明。接入业务登录时继续阅读身份与登录。