开发指南
版本规范
应用版本号按日期设置,同日多次更新使用数字小版本号
版本规范
JSOS 应用版本号按日期设置(CalVer),不使用语义化版本(1.2.3)。
基本规则
| 情况 | 版本号 | 示例 |
|---|---|---|
| 当天首次发布 / 更新 | YYYY.M.D | 2026.11.20 |
| 当天第二次更新 | YYYY.M.D.1 | 2026.11.20.1 |
| 当天第三次更新 | YYYY.M.D.2 | 2026.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) |
| Daemon | daemon/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/ 删除的应用,其注册表条目会在下次打包时自动移除。