目录结构

小程序包就是一个小目录。容器读取页面清单、全局脚本与样式、页面三件套以及包内图片。

包结构

<package>/
├── app.json          # 必需：页面清单与窗口配置
├── app.js            # 可选：App() 应用级对象
├── app.wxss          # 可选：全局样式
├── meta.json         # 可选：仅商店上架使用，不会装进小程序包
├── icon.png          # 可选：商店封面，同样不装进包
├── images/           # 可选：image 组件读取的本地资源
└── pages/
    ├── index/
    │   ├── index.wxml  # 必需
    │   ├── index.wxss  # 必需（可以为空，但文件要存在）
    │   └── index.js    # 必需
    └── detail/
        ├── detail.wxml
        ├── detail.wxss
        └── detail.js

app.json

{
  "pages": ["pages/index/index", "pages/detail/detail"],
  "window": {
    "backgroundColor": "#141518",
    "navigationBarTitleText": "我的小程序"
  }
}

app.js 与 app.wxss

启动时先执行 app.js 注册 App()，再加载 app.wxss 作为全局样式。 页面上的样式会叠加在全局样式之上，内联 style 优先级最高。

// app.js
App({
  onLaunch(options) {},
  globalData: { token: '' }
});

页面文件

每个页面需要 .wxml、.wxss、.js 三个文件； .js 中使用 Page({}) 注册。页面可以带 query： /pages/detail/detail?id=7。

加载顺序

1. 启动器确定包目录：商店安装的 miniapps/<id>/，或 NXKIT_MINIAPP_DEV 指定的目录。
2. 读取 app.json、app.js、app.wxss。
3. 打开 pages[0]，创建 QuickJS 上下文并执行页面 JS。
4. 依次触发 onLoad(query)、onShow()；首次绘制后触发 onReady()。
5. 解析 WXML、WXSS，按页面数据生成渲染树；setData 后重建并重绘。
6. 窗口尺寸变化会重算根节点尺寸，rpx 比例保持 750 设计稿基准。

任何一步失败都会在页面中央显示红色错误文字，不会白屏。错误文本见 错误与排查。

示例包位置

client/resources/miniapps/demo/
client/resources/miniapps/hello/
client/resources/miniapps/playground/

这些包同时是商店种子数据：服务端首次启动时会把它们导入数据库。 复制一个目录改名为新的 <id> 即可开始开发，ID 需匹配 ^[a-z0-9][a-z0-9_-]{1,63}$。其中 playground 覆盖了事件、表单、轮播、存储、路由与新组件的完整示例。

上架用的 meta.json

{
  "title": "演示小程序",
  "summary": "一句话简介",
  "description": "详细介绍",
  "category": "示例",
  "developer": "NXKit",
  "version": "0.1.0",
  "published": true
}

字段约束与上传流程见 商店与上架。