星河小程序前端框架

September 9, 2026 · View on GitHub

项目结构

本项目由多个包组成：

  • common：各分包通用公共工具函数。
  • compiler：小程序源码编译工具。
  • components：内置小程序标准组件。
  • container-sdk：Web 端小程序容器运行时 SDK（createContainer，不含 UI），宿主可嵌入接入，用法见其 README。
  • container：容器 demo，消费 container-sdk，index.html 为演示入口（应用列表 + 手机壳）。
  • jdimina：webview sdk，为 webview 组件提供调用协议。
  • render：渲染层，负责 UI 展示与消息处理。
  • server：Web 端网络请求代理服务器，用于处理跨域请求。
  • service：逻辑层（JavaScript 运行时、worker 线程、消息通道）。

环境要求

要求使用 Node.js 22.22.3+ 和 pnpm 12.2.0+。仓库已配置 Volta Node.js 22.22.3，并通过 packageManager 固定 pnpm 12.2.0；如果使用 Volta，可直接在 fe/ 目录执行 pnpm 命令。

开始使用

安装说明

# 进入前端工作区
cd fe

# 安装依赖
pnpm install

开发说明

# 编译 ../examples/miniprogram/ 目录下的所有小程序
pnpm compile

# 忽略本地编译缓存，强制重新编译 ../examples/miniprogram/ 目录下的所有小程序
pnpm compile --force

# 构建（开发环境，不压缩）
pnpm build:dev

# 构建（生产环境，压缩）
pnpm build

# 预览生产构建
pnpm preview

# Web 开发
pnpm dev

# 原生容器调试
pnpm dev:native

# 运行测试
pnpm test

# 生成小程序包
# 注意：需要 shared/jsapp 目录存在
pnpm generate:app

# 生成 SDK 包
# 注意：需要先执行构建命令
pnpm generate:sdk

pnpm dev 先构建依赖，再统一启动代理和 Vite；按 Ctrl+C 会同时停止两个服务。 开发端口 5173 被占用时会直接报错并停止本次启动的代理，不会自动切换端口。 pnpm test:scripts 包含真实开发进程的退出、重启和端口冲突回归；Windows 或本机开发端口正在使用时跳过这组进程测试。

资源生成工具

pnpm compile

编译 ../examples/miniprogram/ 目录下的所有小程序，并将产物输出到 packages/container/public。

默认情况下，命令会读取 packages/container/public/compile-cache.json：

  • 完全未变化的小程序会整个跳过。
  • 只有普通源文件变化时，会根据持久化依赖图计算受影响页面，并只运行需要的 view、logic 或 style 阶段。
  • 编译器、JSON 配置或文件结构发生变化时，会自动回退为整个小程序全量编译。

如需忽略本地缓存并重新编译全部示例小程序，可以执行：

pnpm compile --force

也支持简写参数：

pnpm compile -f

pnpm generate:app

将编译好的小程序打包并复制到仓库根目录的 shared/jsapp 中。

注意事项：

  • 运行前必须确保 shared/jsapp 目录已存在，否则命令将终止
  • 会自动递增小程序的版本号
  • 生成的资源包括 config.json 配置文件和 [appId].zip 代码包

pnpm generate:sdk

将构建好的 SDK 打包并复制到仓库根目录的 shared/jssdk 中。

注意事项：

  • 运行前必须先执行构建命令 pnpm build 或 pnpm build:dev
  • 会自动递增 SDK 的版本号
  • 生成的资源包括 config.json 配置文件和 main.zip SDK 包

vConsole 调试

JSSDK 直接依赖 vConsole，并随 pageFrame 静态同步打包；只有检测到 vConsole 启用标记时才会初始化。pageFrame 会在 render 初始化前检查 URL 参数，Web 容器会通过 pageFrame URL 参数默认启用；三端 SDK 的调试位开启后也会追加同一个 URL 参数。

各端触发条件：

  • Web 容器：加载 pageFrame 时总是追加 ?vconsole=1
  • Android：Dimina.DiminaConfig.Builder().setDebugMode(true)
  • iOS：Debug 构建，或 DMPAppConfig.isDebugMode = true
  • Harmony：debug HAP，或 DMPAppConfig.isDebugMode = true

注意事项：

  • vConsole 随 pageFrame 静态同步打包，只有启用标记存在时才会初始化
  • Web 容器默认追加启用标记；三端 native 由各自 debug 位控制是否追加启用标记

dmcc 编译工具

请参考编译工具使用说明。