夜雨聆风学习资料网

ARTICLE · 1398046

Obsidian 插件发布实录:从本地打包到 GitHub 与社区上架

Obsidian 插件发布实录:从本地打包到 GitHub 与社区上架
WECHAT ARTICLE2026-11-22

Obsidian 插件发布实录:从本地打包到 GitHub 与社区上架

CONTENTS · 本期看点

01

一、本次发布结果

02

二、准备可以分享的插件

03

三、创建个人 GitHub 公开仓库

— 公众号封面-青绿版

把一个本地可用的 Obsidian 插件分享给别人,需要完成打包、上传源码、发布安装文件三个环节。如果希望用户直接在 Obsidian 的社区插件市场搜索安装,还需要另外申请官方目录审核。

这篇笔记记录“赚钱行情”1.3.0 的实际发布过程,包括遇到的 GitHub 登录问题及解决方法。

01

PART

一、本次发布结果

CHAPTER

项目
实际结果
平台
Obsidian,不是 Joplin
插件名称 / ID
赚钱行情 / a-share-watchlist
发布版本
1.3.0
源码仓库
charle/obsidian-a-share-watchlist
正式版本
Release 1.3.0
自动构建
GitHub Actions 已成功
验证范围
TypeScript 检查、构建和远程安装附件核验通过;未做桌面端及移动端完整交互测试
社区插件目录
尚未提交申请,不能把 Release 发布成功当成市场上架成功

— 发布流程

02

PART

二、准备可以分享的插件

CHAPTER

本地插件位于 .obsidian/plugins/obsidian-a-share-watchlist/。它使用 Obsidian API,因此不能直接改后缀变成 Joplin 的 .jpl 插件。

发布前执行:

powershell

cd "D:\Charle\obsidian\obsidian\.obsidian\plugins\obsidian-a-share-watchlist"

npm install

npm run build

已有完整锁文件时,也可以用 npm ci 安装确定版本的依赖。本项目的 build 会先执行 TypeScript 检查,再用 esbuild 生成 main.js。

手动安装与 Release 的核心文件是:

text

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 加入:

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

通常为插件单独建立一个个人账号下的公开仓库。本次仓库为:

text

https://github.com/charle/obsidian-a-share-watchlist.git

你的仓库存放源码和安装文件;Obsidian 官方目录只登记插件信息与仓库地址。二者职责不同。

新项目首次初始化时,可以在源码目录执行:

cmd

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 账号密码,出现:

text

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 执行:

cmd

winget install --id GitHub.cli --exact

安装后重新打开终端。如果 gh 还没有进入 PATH,直接使用完整路径。

2. 在 CMD 发起登录

cmd

"C:\Program Files\GitHub CLI\gh.exe" auth login --hostname github.com --git-protocol https --web

当终端询问:

text

Authenticate Git with your GitHub credentials? (Y/n)

输入 Y。终端会显示一次性验证码,格式类似 XXXX-XXXX,按回车打开浏览器。

3. 用电脑或手机浏览器完成授权

手机不需要安装 GitHub App 或其他软件。打开:

https://github.com/login/device

确认登录的是有目标仓库写入权限的账号,本次为 charle。输入当前电脑终端显示的验证码,点击 Continue,再点击 Authorize GitHub CLI。

验证码来自终端,不是短信。每次重新发起登录可能生成新码,旧截图上的验证码不能反复使用。

授权成功后,终端会出现类似:

text

Authentication complete.

Configured git protocol

这只表示登录完成,仍需要执行推送。继续配置并检查:

cmd

"C:\Program Files\GitHub CLI\gh.exe" auth setup-git

"C:\Program Files\GitHub CLI\gh.exe" auth status

截图归档说明:本次会话提供过手机设备授权页和 CMD 登录成功截图,但其临时图片文件在整理时已失效,无法复制进笔记。本笔记以步骤和终端文本记录对应过程,所配发布流程图为另行绘制,并非原始截图。

05

PART

五、推送代码和版本标签

CHAPTER

在 CMD 中执行:

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 会:

1

检查标签与 manifest.json、package.json 版本是否一致。

2

执行 npm ci 和 npm run build。

3

创建正式 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

1

从 Release 下载同一版本的三个安装文件。

2

在目标笔记库创建 .obsidian/plugins/a-share-watchlist/。

3

放入这三个文件,重新加载 Obsidian。

4

在“设置 → 第三方插件”中启用“赚钱行情”。

5

点击侧边栏折线图图标,或运行“打开赚钱行情”命令。

如果笔记库使用了自定义配置文件夹,需要把 .obsidian 替换成实际配置目录。

08

PART

八、申请进入 Obsidian 社区插件市场

CHAPTER

这部分是下一阶段,本次尚未提交。

1. 完善公开仓库

检查源码、README、manifest、Release 和开源许可证。当前还需要确定并补充 LICENSE,常见选择为 MIT,具体选择由作者决定。

README 应说明插件功能、安装方式、联网行为和本地数据存储。“赚钱行情”依赖东方财富、新浪财经、同花顺等公开行情接口;自选列表与采集历史保存在本地插件目录。公开接口可能延迟、限流或调整。

2. 修改官方插件目录

打开官方 community-plugins.json,通过 GitHub 的 Fork 和编辑流程,在数组末尾添加条目。提交前检查 ID 是否已被占用,并注意 JSON 逗号位置。

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:

1

修改源码,并同步更新 manifest、package、锁文件、versions 和发布说明。

2

构建并在 Obsidian 内测试。

3

提交代码,创建新标签并推送:

cmd

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,明天又是新的一天,财富满满的一天,元气满满的一天。

如果你觉得今天这篇有收获,欢迎点赞、在看、转发三连,我们下篇见。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料