ARTICLE · 1398046
Obsidian 插件发布实录:从本地打包到 GitHub 与社区上架
Obsidian 插件发布实录:从本地打包到 GitHub 与社区上架
CONTENTS · 本期看点
一、本次发布结果
二、准备可以分享的插件
三、创建个人 GitHub 公开仓库

— 公众号封面-青绿版
把一个本地可用的 Obsidian 插件分享给别人,需要完成打包、上传源码、发布安装文件三个环节。如果希望用户直接在 Obsidian 的社区插件市场搜索安装,还需要另外申请官方目录审核。
这篇笔记记录“赚钱行情”1.3.0 的实际发布过程,包括遇到的 GitHub 登录问题及解决方法。
01
PART
一、本次发布结果
CHAPTER
| 1.3.0 | |

— 发布流程
02
PART
二、准备可以分享的插件
CHAPTER
本地插件位于 .obsidian/plugins/obsidian-a-share-watchlist/。它使用 Obsidian API,因此不能直接改后缀变成 Joplin 的 .jpl 插件。
发布前执行:
cd "D:\Charle\obsidian\obsidian\.obsidian\plugins\obsidian-a-share-watchlist"
npm install
npm run build
已有完整锁文件时,也可以用 npm ci 安装确定版本的依赖。本项目的 build 会先执行 TypeScript 检查,再用 esbuild 生成 main.js。
手动安装与 Release 的核心文件是:
a-share-watchlist/
├── main.js
├── manifest.json
└── styles.css
安装目录名称应与 manifest.json 的 id 一致。本项目 ID 为 a-share-watchlist,所以分享给其他用户时使用这个目录名;本机原开发目录名称不影响打包。
本次发现 manifest.json 已是 1.3.0,而 package.json 与锁文件仍为 1.2.0。在发布源码副本中统一为 1.3.0,并在 versions.json 加入:
"1.3.0": "1.4.0"
这表示插件 1.3.0 要求最低 Obsidian 版本为 1.4.0。它是现有声明,不代表已在该旧版本完成实机验证。
源码发布副本放在 插件发布/赚钱行情/repository/。使用 .gitignore 排除依赖、个人设置、行情历史和环境文件,例如 node_modules/、data.json、history.json、.env。不要把整个笔记库上传。
手动安装 ZIP:[[插件发布/赚钱行情/1.3.0/a-share-watchlist-1.3.0-obsidian.zip]]。
03
PART
三、创建个人 GitHub 公开仓库
CHAPTER
通常为插件单独建立一个个人账号下的公开仓库。本次仓库为:
https://github.com/charle/obsidian-a-share-watchlist.git
你的仓库存放源码和安装文件;Obsidian 官方目录只登记插件信息与仓库地址。二者职责不同。
新项目首次初始化时,可以在源码目录执行:
git init
git add .
git commit -m "Release A-share watchlist plugin 1.3.0"
git branch -M main
git remote add origin https://github.com/charle/obsidian-a-share-watchlist.git
本项目已经完成初始化、提交和远程配置,不需要重复执行这些命令。 若提示 remote origin already exists,用 git remote -v 检查已有地址;只有地址确实错误时才使用 git remote set-url origin 新地址。
04
PART
四、解决 GitHub 登录失败
CHAPTER
本次最主要的问题是推送时输入了邮箱和 GitHub 账号密码,出现:
remote: Invalid username or token. Password authentication is not supported for Git operations.
fatal: Authentication failed
GitHub 不允许使用账号密码进行 HTTPS Git 推送。推荐通过 GitHub CLI 的浏览器授权配置凭据,不用手动复制 Token。
1. 安装 GitHub CLI
在 PowerShell 或 CMD 执行:
winget install --id GitHub.cli --exact
安装后重新打开终端。如果 gh 还没有进入 PATH,直接使用完整路径。
2. 在 CMD 发起登录
"C:\Program Files\GitHub CLI\gh.exe" auth login --hostname github.com --git-protocol https --web
当终端询问:
Authenticate Git with your GitHub credentials? (Y/n)
输入 Y。终端会显示一次性验证码,格式类似 XXXX-XXXX,按回车打开浏览器。
3. 用电脑或手机浏览器完成授权
手机不需要安装 GitHub App 或其他软件。打开:
https://github.com/login/device
确认登录的是有目标仓库写入权限的账号,本次为 charle。输入当前电脑终端显示的验证码,点击 Continue,再点击 Authorize GitHub CLI。
验证码来自终端,不是短信。每次重新发起登录可能生成新码,旧截图上的验证码不能反复使用。
授权成功后,终端会出现类似:
Authentication complete.
Configured git protocol
这只表示登录完成,仍需要执行推送。继续配置并检查:
"C:\Program Files\GitHub CLI\gh.exe" auth setup-git
"C:\Program Files\GitHub CLI\gh.exe" auth status
截图归档说明:本次会话提供过手机设备授权页和 CMD 登录成功截图,但其临时图片文件在整理时已失效,无法复制进笔记。本笔记以步骤和终端文本记录对应过程,所配发布流程图为另行绘制,并非原始截图。
05
PART
五、推送代码和版本标签
CHAPTER
在 CMD 中执行:
cd /d "D:\Charle\obsidian\obsidian\插件发布\赚钱行情\repository"
git push -u origin main
git push origin 1.3.0
CMD 使用 cd /d 才能同时切换盘符和目录;PowerShell 使用 cd "路径" 即可。
本项目已经创建 1.3.0 标签,不需要再次创建。其他新版本需要先提交变更,再执行对应的 git tag 版本号。
Obsidian 发布标签应与 manifest.json 的版本完全一致,本例使用 1.3.0,不加 v 前缀。
06
PART
六、让 GitHub 自动发布安装文件
CHAPTER
仓库已加入 .github/workflows/release.yml。推送版本标签后,Actions 会:
检查标签与 manifest.json、package.json 版本是否一致。
执行 npm ci 和 npm run build。
创建正式 GitHub Release,并上传 main.js、manifest.json、styles.css。
查看 Actions 是否成功,再检查 Releases。
三个安装文件必须作为独立附件存在。 GitHub 自动生成的 Source code 压缩包,或只有一个插件 ZIP,都不能代替 Obsidian 自动安装所需的独立附件。
本次已核验:远程 main 和 1.3.0 标签均指向 e7586ce;Actions 成功;正式 Release 的三个附件均已上传完成。
07
PART
七、其他人如何手动安装
CHAPTER
从 Release 下载同一版本的三个安装文件。
在目标笔记库创建 .obsidian/plugins/a-share-watchlist/。
放入这三个文件,重新加载 Obsidian。
在“设置 → 第三方插件”中启用“赚钱行情”。
点击侧边栏折线图图标,或运行“打开赚钱行情”命令。
如果笔记库使用了自定义配置文件夹,需要把 .obsidian 替换成实际配置目录。
08
PART
八、申请进入 Obsidian 社区插件市场
CHAPTER
这部分是下一阶段,本次尚未提交。
1. 完善公开仓库
检查源码、README、manifest、Release 和开源许可证。当前还需要确定并补充 LICENSE,常见选择为 MIT,具体选择由作者决定。
README 应说明插件功能、安装方式、联网行为和本地数据存储。“赚钱行情”依赖东方财富、新浪财经、同花顺等公开行情接口;自选列表与采集历史保存在本地插件目录。公开接口可能延迟、限流或调整。
2. 修改官方插件目录
打开官方 community-plugins.json,通过 GitHub 的 Fork 和编辑流程,在数组末尾添加条目。提交前检查 ID 是否已被占用,并注意 JSON 逗号位置。
{
"id": "a-share-watchlist",
"name": "赚钱行情",
"author": "Junling",
"description": "查看 A 股自选行情、市场概览和当日价格走势,支持自动刷新与涨跌幅提醒。",
"repo": "charle/obsidian-a-share-watchlist"
}
条目中的 ID、名称、作者和描述应与准备提交时的 manifest.json 保持一致;上方描述是建议文案,正式提交前需同步更新 manifest,或改用其现有描述。
3. 提交 Pull Request 并处理审核反馈
PR 标题可使用 Add plugin: 赚钱行情。按官方当时提供的模板填写检查项,等待自动检查和人工审核;若要求修改源码或文档,完成修改后再跟进。
目录申请被合并、目录更新后,用户才可以在 Obsidian 的“第三方插件 → 浏览”中搜索安装。审核时间不固定。
09
PART
九、以后如何发布更新
CHAPTER
例如准备发布 1.3.1:
修改源码,并同步更新 manifest、package、锁文件、versions 和发布说明。
构建并在 Obsidian 内测试。
提交代码,创建新标签并推送:
git add .
git commit -m "Release 1.3.1"
git tag 1.3.1
git push origin main
git push origin 1.3.1
Actions 会为新标签生成新 Release。不要复用已发布版本号,也不要为了更新而更改插件 ID。进入社区目录后,常规版本更新通常通过同一仓库的 Release 完成,无需每次新增目录条目。
我是 Zora,明天又是新的一天,财富满满的一天,元气满满的一天。
如果你觉得今天这篇有收获,欢迎点赞、在看、转发三连,我们下篇见。















































































