drukscode-v2/docs/zh/extensions/publish.md

发布到市场

模块市场是一个由 GitHub 支撑的社区 JS/CSS 扩展模块目录。没有后端 —— 应用直接从本仓库拉取目录文件,因此贡献就是一个普通的 pull request 流程。

::: info 规范规则 权威的提交规则、字段 schema、审核清单和 CI 校验位于 modules/README.md。本页是快速入门。 :::

目录布局

modules/
├── registry.json        # 面向应用的目录
├── submissions.json     # CI 生成的 PR / 贡献者元数据
├── README.md            # 贡献者指南
└── <module-folder>/     # 每个模块

应用同时拉取 registry.json 和 submissions.json,并只显示两者中都存在的模块,使应用内目录与实际合并的 PR 保持一致。

添加一个模块

1. 在 modules/ 下创建一个 kebab-case 文件夹:

   modules/my-module/
   ├── module.json    # 必需
   ├── main.js        # 必需
   ├── style.css      # 可选
   └── icon.png       # 可选,≤256KB
   

2. 向 registry.json 添加一个条目:

   {
     "id": "my-module",
     "path": "my-module",
     "name": "My Module",
     "description": "它做什么",
     "icon": "star",
     "category": "CONTENT_ENHANCE",
     "tags": ["demo"],
     "version": "1.0.0",
     "author": { "name": "You" },
     "runAt": "DOCUMENT_END",
     "permissions": ["DOM_ACCESS"],
     "urlMatches": [{ "pattern": "*://example.com/*" }],
     "hasCss": false
   }
   

   注意:在 registry.json 中,version 是一个 semver 字符串(不同于 module.json 里是对象),并有两个额外字段 —— path 和 hasCss。

3. 保持 registry.json 与 module.json 一致 —— id、name、version、runAt 和 permissions 必须相符。CI 会强制这一点。

4. 开一个 pull request。CI 会自动运行校验器。

CI 校验什么

python3 .github/scripts/ci/validate_modules.py 检查:

• JSON 合法性与必填字段
• 允许的枚举值(category、runAt、permissions、configItems.type)
• registry.json ↔ module.json 一致性
• kebab-case 文件夹名;无孤儿或鬼条目;无重复 id/path
• 必需文件存在;hasCss 与 style.css 的存在一致
• iconUrl 大小/扩展名限制
• main.js 中无顶层 return
• getConfig 键与声明的 configItems 对应

浏览器扩展不同

社区市场只收录 JS/CSS 模块。MV3 浏览器扩展不是社区目录 —— 浏览器扩展 标签页改为实时搜索 Chrome 网上应用店。见 Chrome MV3 扩展。

镜像

目录文件和模块图标先经由全局镜像,以 raw.githubusercontent.com 和 jsDelivr 作为自动回退,使商店在各地(包括中国大陆)都能快速加载。默认客户端缓存为一小时,因此合并的模块无需应用更新即可传播。