SiYuan 插件市场提交全解plugin.json、平台字段与上架校验一次讲清【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan思源笔记SiYuan是一个开源、隐私优先的自托管知识工作空间其社区集市bazaar是官方分发的插件市场开发者把扩展包提交进集市索引后用户即可在应用内浏览、安装和更新。这篇文章从客户端源码出发讲清楚一个插件包要进入 SiYuan 插件市场到底经过哪些校验、plugin.json里哪些字段真正起作用以及上架失败时该怎么自查。相关逻辑集中在 kernel/bazaar/ 目录所有结论都可以对照源码复核。进入集市包列表的第一道闸门平台兼容性很多开发者提交后发现自己的包没出现原因往往不在内容而在平台匹配。客户端在拉取集市包时会对每一个包做兼容性判断核心逻辑在 kernel/bazaar/plugin.go 的IsIncompatiblePluginfrontends决定插件出现在哪个前端环境取值如desktop、mobile或all表示全平台backends决定插件能否随哪个后端容器运行例如 Linux 标准容器、Docker 等kernels如果插件包含内核级扩展Go 编写的 kernel plugin这一项缺省时插件本体可以装但内核部分不会启动。任何一个维度不匹配该包就会被标记为BazaarIncompatible安装和更新按钮都会被禁用。所以提交前先在plugin.json里把三类平台声明写全比事后排查省时得多。plugin.json 必填字段速查集市把每个包抽象成一个Package结构定义见 kernel/bazaar/package.go其中需要你手工填写的字段与展示规则如下字段作用注意事项name包名也是安装目录名不必与仓库名相同但必须稳定改名等于新包version语义化版本号客户端用它与线上版本比较判断是否可更新minAppVersion要求的最低思源版本低于该版本的用户会看到禁止安装/更新displayName多语言显示名键为zh_CN、en_US等缺失时回退default→endescription多语言简介集市卡片上展示的就是这里的文本author/url作者与仓库地址搜索时两者都会参与关键词匹配keywords搜索关键词决定用户能否通过搜索词找到你的包funding赞助入口支持 OpenCollective、Patreon、GitHub Sponsors 或自定义链接一个最小可用的配置骨架大致如下完整字段以源码结构体为准{ name: my-plugin, version: 1.0.0, minAppVersion: 3.0.0, frontends: [desktop, mobile], backends: [all] }图标与预览图集市卡片长什么样用户在集市里看到的就是由icon.png和preview.png拼成的卡片图标在列表左侧预览图在详情页顶部展示线上还会做缩放处理。两点实操建议预览图要一眼看懂集市卡片区域不大把插件最核心的界面状态拍进去避免放整页长截图横版比例优先16:9 或 4:3 的预览图在卡片布局里最稳竖长图会被裁切得很尴尬图标尺寸统一与集市内其他包保持同一视觉密度避免在列表中显得突兀。提交之后发生了什么stage 索引与安装链路理解这条链路很多提交失败类问题自己就解开了。集市数据托管在一个独立仓库中客户端按类型plugins、themes、icons、templates、widgets拉取形如stage/plugins.json的索引文件索引里每个仓库条目都带有commit hash包体本身则按owner/repohash的形式从对象存储下载并解压安装见 kernel/bazaar/install.go。这意味着更新是 hash 驱动的你往仓库 push 新提交后必须让集市索引指向新 hash否则用户拿到的仍是旧包版本比较靠 semver本地已装版本与线上版本做语义化比较得出Outdated标记再驱动一键批量更新下载计数是异步上报的安装完成后客户端会异步调用统计接口累加下载量页面上的数字并非实时。信任声明与安全边界首次打开集市面板时用户会看到一段信任说明后才进入包列表见 app/src/config/bazaar.ts 中的genHTML。它明确告诉用户三件事集市包代码会经过社区审查、所有包开源可自查、发现恶意行为可以举报。对插件作者而言这等于一份隐性契约代码必须放在公开仓库中用户随时可以拉下来审计不要声明超出功能所需的能力权限越克制越容易通过社区评审敏感数据用户库内容、API 密钥的读取行为要在 README 中显式说明。提交被拒与安装失败的排查清单按命中率从高到低自查plugin.json解析失败字段拼写错误、JSON 语法问题会导致包从列表中整个消失先在本地用 JSON 校验器过一遍name与安装目录名不一致客户端按目录名匹配包名不一致时更新会被当成全新安装minAppVersion高于用户版本这类用户会看到禁用状态这是设计行为而非故障平台字段漏填只声明frontends: [desktop]的包在移动端集市里不会出现属正常过滤网络/离线客户端先探测集市服务可用性离线时包列表会直接为空并给出提示仓库 hash 未更新push 了新代码但集市索引仍指向旧 hash用户装到的还是老版本。下一步先让本地插件跑起来建议的顺序是在数据目录的plugins/包名/下手工放好plugin.json与源码确认最新桌面版能正常加载再把version与minAppVersion校准到当前发布版本最后提交进集市仓库并检查索引是否指向了新 hash。把这三步拆成独立可验证的小动作比一次性打包提交更不容易卡住。如果你的插件目前只面向桌面端先只声明frontends: [desktop]跑通全流程后再扩到移动端是最稳妥的上架路径。【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/8/31 19:48:14 · 阅读 1.2k SiYuan 插件市场提交全解：plugin.json、平台字段与上架校验一次讲清
SiYuan 插件市场提交全解plugin.json、平台字段与上架校验一次讲清【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan思源笔记SiYuan是一个开源、隐私优先的自托管知识工作空间其社区集市bazaar是官方分发的插件市场开发者把扩展包提交进集市索引后用户即可在应用内浏览、安装和更新。这篇文章从客户端源码出发讲清楚一个插件包要进入 SiYuan 插件市场到底经过哪些校验、plugin.json里哪些字段真正起作用以及上架失败时该怎么自查。相关逻辑集中在 kernel/bazaar/ 目录所有结论都可以对照源码复核。进入集市包列表的第一道闸门平台兼容性很多开发者提交后发现自己的包没出现原因往往不在内容而在平台匹配。客户端在拉取集市包时会对每一个包做兼容性判断核心逻辑在 kernel/bazaar/plugin.go 的IsIncompatiblePluginfrontends决定插件出现在哪个前端环境取值如desktop、mobile或all表示全平台backends决定插件能否随哪个后端容器运行例如 Linux 标准容器、Docker 等kernels如果插件包含内核级扩展Go 编写的 kernel plugin这一项缺省时插件本体可以装但内核部分不会启动。任何一个维度不匹配该包就会被标记为BazaarIncompatible安装和更新按钮都会被禁用。所以提交前先在plugin.json里把三类平台声明写全比事后排查省时得多。plugin.json 必填字段速查集市把每个包抽象成一个Package结构定义见 kernel/bazaar/package.go其中需要你手工填写的字段与展示规则如下字段作用注意事项name包名也是安装目录名不必与仓库名相同但必须稳定改名等于新包version语义化版本号客户端用它与线上版本比较判断是否可更新minAppVersion要求的最低思源版本低于该版本的用户会看到禁止安装/更新displayName多语言显示名键为zh_CN、en_US等缺失时回退default→endescription多语言简介集市卡片上展示的就是这里的文本author/url作者与仓库地址搜索时两者都会参与关键词匹配keywords搜索关键词决定用户能否通过搜索词找到你的包funding赞助入口支持 OpenCollective、Patreon、GitHub Sponsors 或自定义链接一个最小可用的配置骨架大致如下完整字段以源码结构体为准{ name: my-plugin, version: 1.0.0, minAppVersion: 3.0.0, frontends: [desktop, mobile], backends: [all] }图标与预览图集市卡片长什么样用户在集市里看到的就是由icon.png和preview.png拼成的卡片图标在列表左侧预览图在详情页顶部展示线上还会做缩放处理。两点实操建议预览图要一眼看懂集市卡片区域不大把插件最核心的界面状态拍进去避免放整页长截图横版比例优先16:9 或 4:3 的预览图在卡片布局里最稳竖长图会被裁切得很尴尬图标尺寸统一与集市内其他包保持同一视觉密度避免在列表中显得突兀。提交之后发生了什么stage 索引与安装链路理解这条链路很多提交失败类问题自己就解开了。集市数据托管在一个独立仓库中客户端按类型plugins、themes、icons、templates、widgets拉取形如stage/plugins.json的索引文件索引里每个仓库条目都带有commit hash包体本身则按owner/repohash的形式从对象存储下载并解压安装见 kernel/bazaar/install.go。这意味着更新是 hash 驱动的你往仓库 push 新提交后必须让集市索引指向新 hash否则用户拿到的仍是旧包版本比较靠 semver本地已装版本与线上版本做语义化比较得出Outdated标记再驱动一键批量更新下载计数是异步上报的安装完成后客户端会异步调用统计接口累加下载量页面上的数字并非实时。信任声明与安全边界首次打开集市面板时用户会看到一段信任说明后才进入包列表见 app/src/config/bazaar.ts 中的genHTML。它明确告诉用户三件事集市包代码会经过社区审查、所有包开源可自查、发现恶意行为可以举报。对插件作者而言这等于一份隐性契约代码必须放在公开仓库中用户随时可以拉下来审计不要声明超出功能所需的能力权限越克制越容易通过社区评审敏感数据用户库内容、API 密钥的读取行为要在 README 中显式说明。提交被拒与安装失败的排查清单按命中率从高到低自查plugin.json解析失败字段拼写错误、JSON 语法问题会导致包从列表中整个消失先在本地用 JSON 校验器过一遍name与安装目录名不一致客户端按目录名匹配包名不一致时更新会被当成全新安装minAppVersion高于用户版本这类用户会看到禁用状态这是设计行为而非故障平台字段漏填只声明frontends: [desktop]的包在移动端集市里不会出现属正常过滤网络/离线客户端先探测集市服务可用性离线时包列表会直接为空并给出提示仓库 hash 未更新push 了新代码但集市索引仍指向旧 hash用户装到的还是老版本。下一步先让本地插件跑起来建议的顺序是在数据目录的plugins/包名/下手工放好plugin.json与源码确认最新桌面版能正常加载再把version与minAppVersion校准到当前发布版本最后提交进集市仓库并检查索引是否指向了新 hash。把这三步拆成独立可验证的小动作比一次性打包提交更不容易卡住。如果你的插件目前只面向桌面端先只声明frontends: [desktop]跑通全流程后再扩到移动端是最稳妥的上架路径。【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考