ZimaSpace
商店

应用商店配置

无论是公开商店还是私有 Homelab 目录，家庭服务器和 NAS OS 用户订阅后都应保持商店标识稳定。

store-config.json 用于在仓库级别定义商店身份。

作用

构建脚本会读取 store-config.json 并生成：

  • dist/store.json
  • 对应已显式定义 locale 的 dist/store.{locale}.json

最小示例

{
  "version": 2,
  "store_id": "my-awesome-apps",
  "name": {
    "en_US": "My Awesome Apps",
    "zh_CN": "我的应用商店"
  },
  "description": {
    "en_US": "A collection of apps for home server enthusiasts"
  },
  "maintainer": "your-github-username",
  "url": "https://github.com/username/my-appstore"
}

字段

字段 类型 必填 说明
version int 是 必须为 2
store_id string 是 商店唯一标识
name object 是 多语言商店名称
description object 否 多语言商店描述
maintainer string 是 维护者名称
url string 否 项目主页
icon string 否 商店图标 URL

字段详解

version

  • 必填
  • 必须是整数 2
  • 用于标识当前构建流程所面向的协议版本

store_id

  • 必填
  • 是商店的主身份标识
  • 一旦已有用户订阅，建议保持稳定
  • 应尽量选成全局可区分的值

name

  • 必填
  • 必须是 locale 到文本的对象，而不是纯字符串
  • 应始终至少包含 en_US
  • 最终会成为生成后 store.json 中的展示名称

description

  • 可选
  • 也是按 locale 组织的对象
  • 适合为客户端中的商店提供简短介绍

maintainer

  • 必填
  • 用普通字符串表示维护者、组织或拥有者名称

url

  • 可选
  • 可以是项目主页、仓库地址或其他公开页面

icon

  • 可选
  • 这是商店级别的直接 URL 字段
  • 和应用资源不同，它不是从应用目录资产构建出来的路径

store_id 规则

  • 只允许字母、数字、.、_、-
  • 允许大写输入，但构建时会规范化为小写
  • 必须至少包含一个字母或数字
  • 应尽量保证全局可区分
  • 不要使用 zimaos-appstore 之类的保留值

校验预期

可以把下面这些当作输入契约：

  • 文件本身必须是合法 JSON
  • version 必须匹配当前协议版本
  • name 应该是对象而不是纯字符串
  • locale 键应使用 ll_CC 格式
  • URL 类型字段应当已经是公开可访问地址

本地化行为

商店级本地化文本来自：

  • name
  • description

只有这些字段里显式声明过的 locale 才会生成对应的 store.{locale}.json。

输入到输出的映射

源字段 生成位置 说明
version store.json.version 作为协议元数据保留
store_id store.json.store_id 构建时按规则规范化
name.<locale> store.{locale}.name 按生成语言解析
description.<locale> store.{locale}.description 仅对显式定义的 locale 生成
maintainer store.json.maintainer 作为纯字符串复制
url store.json.url 作为纯字符串复制
icon store.json.icon 作为纯字符串 URL 复制

输出行为

构建脚本总会生成默认语言文件：

  • dist/store.json

只有当某个 locale 在商店本地化文本中被显式定义时，才会额外生成：

  • dist/store.zh_CN.json
  • dist/store.de_DE.json

这样既支持多语言展示，也避免无意义地膨胀输出。

实践建议

  • 至少提供 name.en_US
  • 如果希望客户端里能看到商店简介，就补上 description
  • 一旦有用户开始订阅，尽量不要再修改 store_id

常见错误

  • 把 name 写成单个字符串，而不是多语言对象
  • 在已有用户使用后修改 store_id
  • 使用 en_us 而不是 en_US
  • 误以为 supported-languages.json 中列出的每个语言都会自动生成 store.{locale}.json