JSOS
开发指南

版本规范

应用版本号按日期设置,同日多次更新使用数字小版本号

版本规范

JSOS 应用版本号按日期设置(CalVer),不使用语义化版本(1.2.3)。

基本规则

情况版本号示例
当天首次发布 / 更新YYYY.M.D2026.11.20
当天第二次更新YYYY.M.D.12026.11.20.1
当天第三次更新YYYY.M.D.22026.11.20.2
次日更新YYYY.M.D(新日期)2026.11.21
  • 月、日不补零:2026.8.5,不是 2026.08.05
  • 小版本号从 1 开始递增,不加前导零
  • 日期与小版本号之间用 . 分隔,不要用 - 或 +

为什么用 .1 而不是 -update1

JSOS 的版本比较逻辑(安装流程、App Store 更新提示、Daemon 更新检测)会把版本按 . 分段转成数字逐段比较:

compareVersions('2026.11.20.1', '2026.11.20')       //  1 → 更新
compareVersions('2026.11.20-update1', '2026.11.20') // -1 → 被判为降级
compareVersions('2026.11.20-1', '2026.11.20')       // -1 → semver 预发布,排序更低
compareVersions('2026.11.20+1', '2026.11.20')       // -1 → 构建元数据被忽略
  • 2026.11.20-update1:第三段 20-update1 转数字为 NaN,按 0 处理 → 比 2026.11.20 更旧
  • 2026.11.20-1:合法 semver,但作为 2026.11.20 的预发布版本,排序更低
  • 2026.11.20+1:semver 构建元数据,比较时被忽略

所以同日多次更新必须使用数字段 .1、.2。

排序

2026.11.20 < 2026.11.20.1 < 2026.11.20.2 < 2026.11.21

四段版本在所有 JSOS 比较逻辑中都能正确排序。

更新机制依赖

场景判定方式
内置应用自动更新注册表版本与本地版本不相等即更新
安装 ZIP / 应用商店compareVersions:更高 → 升级,更低 → 降级提示,相同 → 覆盖安装
Daemon 更新compareVersions(远端 manifest, 本地 manifest)

npm 兼容性

YYYY.M.D.1 不是合法 semver:

  • npm install / npm pack 可正常使用
  • npm publish 会改写版本号(如 2026.11.20.1 → 2026.11.2-0.1)
  • semver 库会拒绝该版本

JSOS 应用通过 ZIP 分发,不依赖 npm publish,因此不受影响。若某个应用需要发布到 npm,保持 package.json 的 version 为三段 semver,把日期版本写进 jsos.version(manifest 优先使用 jsos.version)。

同步更新位置

对象位置
内置应用应用 package.json 的 version(或 jsos.version);重新打包后 public/builtin-apps.json 自动更新
第三方应用应用 package.json 的 version(或 jsos.version)
Daemondaemon/package.json;构建时自动复制到 public/daemon/package.json
系统版本根 package.json 的 version(作为 JSOS_VERSION 注入应用,显示在终端 banner 与设置-关于)

每次发布 / 更新应用时,先确认当天日期,再按上表同步版本号。

内置应用产物保留

scripts/build-apps.js 打包后只保留注册表引用的最新 ZIP:

  • 打包完成 → 更新 public/builtin-apps.json → 删除 public/apps/ 下未被引用的旧版本 ZIP
  • 注册表每个应用只记录一条 zipUrl,安装流程只读取这一条,旧版本 ZIP 不会被使用
  • 旧 ZIP 会随 npm run build 复制进 dist/ 并上传到部署目标,保留它们只会增加部署体积
  • 构建失败时不执行清理,旧产物保留以便排查
  • 需要保留旧产物时加 --keep-old:node scripts/build-apps.js --keep-old

已从 builtin-apps/ 删除的应用,其注册表条目会在下次打包时自动移除。

On this page