先说结论：插件本质上就是一个"带约定入口的 JS 包"
Obsidian 本身用 Electron 构建，插件系统并不神秘：一个插件就是一个符合约定目录结构的文件夹，核心是manifest.json、main.js、styles.css三个文件。Obsidian 启动时扫描.obsidian/plugins/目录，读取 manifest 中的入口文件并加载执行。理解了这一点，剩下的都是 API 层面的学习成本。社区插件用 TypeScript 开发是主流选择，官方提供了完整的类型定义（obsidian.d.ts），API 补全体验良好。
插件三件套的结构与职责
一个最小可用的插件目录如下：
manifest.json：插件身份证。包含id（全局唯一）、name、version、minAppVersion（最低兼容版本）、description、author等字段。isDesktopOnly用于声明是否依赖桌面端能力。main.js：编译后的入口文件。源码通常写在main.ts，由 esbuild 或 tsc 打包输出。Obsidian 只认main.js，源码怎么组织它不关心。styles.css：可选。插件注入的样式，Obsidian 会自动加载，无需手动引入。
值得注意的是manifest.json中的minAppVersion必须与你实际调用的 API 版本匹配——调用了新 API 却声明了过低的最低版本，会在旧版本客户端上直接报错，这是上架审核的常见退回原因。
生命周期：onload 与 onunload 的契约
每个插件类继承自Plugin，Obsidian 在启用插件时调用onload()，在禁用或卸载时调用onunload()。二者的核心契约是对称清理：
onload()中注册的事件监听（registerEvent）、DOM 节点、定时器、全局样式类，必须在onunload()中解除或移除。- 使用
this.registerEvent()、this.registerDomEvent()、this.addCommand()等 helper 注册的资源会被 Obsidian 自动跟踪并在卸载时清理，优先使用这些 helper 而不是裸调addEventListener。 - 常见反模式：在
onload()里给document.body加了 class 或插入了浮动元素，onunload()却不做清理，导致禁用插件后 UI 残留。这类问题在审核中会被明确指出。
开发期频繁重载插件，如果清理逻辑有漏洞，内存和 DOM 泄漏会累积，表现为"越用越卡"，这往往是插件自己的问题而非 Obsidian 的问题。
扩展点一：命令（Command）
命令是插件最基础的扩展点，注册后可通过命令面板（Ctrl/Cmd+P）调用，也可绑定快捷键。命令定义包含id、name和callback（或支持撤销栈的editorCallback）。设计命令时注意两点：一是命令名要自解释，因为命令面板是按名称搜索的；二是对于需要当前有活动编辑器才有意义的操作，使用checkCallback可以在无编辑器时置灰命令，而不是报错。
扩展点二：设置面板（PluginSettingTab）
继承PluginSettingTab并在onload中通过addSettingTab注册，即可获得官方风格的设置界面。设置值通常持久化到插件目录下的data.json，通过loadData()/saveData()读写。实践建议：
- 设置项变更后立即保存，不要依赖用户"点确定"的习惯。
- 复杂设置提供默认值兜底，
data.json被手动删除或损坏时插件不应崩溃。 - 数值型设置做边界校验，避免用户输入非法值导致运行时异常。
扩展点三：编辑器扩展（MarkdownPostProcessor 与 CodeMirror）
这是插件能力的天花板所在，分两个层次：
MarkdownPostProcessor：对渲染后的 HTML 做后处理。典型用途是自定义代码块渲染——监听language-xxx代码块，替换为图表、倒计时、查询结果等富内容。Dataview、Charts 类插件走的都是这条路。- CodeMirror 6 扩展：Obsidian 的编辑器内核是 CM6，插件可以通过
registerEditorExtension注入底层扩展（如行内高亮、自动补全、gutter 装饰）。能力更强，但学习曲线陡峭，需要理解 CM6 的 State、ViewPlugin、Decoration 模型。
选择建议：只影响阅读视图的用 PostProcessor；需要在编辑态实时干预输入的才上 CM6。
开发与调试：热重载工作流
官方推荐的调试流程如下：
- 用官方示例插件（obsidian-sample-plugin）作为模板克隆到测试库的
.obsidian/plugins/你的插件id/目录。 npm install && npm run dev启动 esbuild 持续构建，源码变更自动重新打包main.js。- 安装 Hot-Reload 社区插件，它监听插件文件变化并自动重载，省去手动"禁用-启用"的循环。
- 用 Ctrl/Cmd+Shift+I 打开开发者工具（Electron 内置 Chromium DevTools），断点、Console、Network 都可用。
- 建议专门建一个"测试库"（vault）做开发，避免在主力库上调试导致数据被意外修改。
调试时的一个实用技巧：在 DevTools 中可以通过app.plugins.plugins['插件id']直接访问插件实例，快速验证状态和方法行为。
发布到社区商店：流程与审核要点
上架社区插件商店的流程是：在 GitHub 建仓库并打好 release（附 manifest.json、main.js、styles.css）→ 向 obsidian-releases 仓库提交 PR，在 community-plugins.json 中追加条目 → 通过机器人自动校验后等待人工审核。
审核的高频退回点包括：
- manifest 与 release 不一致：版本号、文件哈希不匹配。
- 清理不彻底：onunload 未正确移除 DOM、事件、定时器。
- 安全与隐私：未经明确告知收集用户数据、请求了与功能无关的权限（如不必要的网络请求）。
- 命名与描述：名称含误导性词汇，或 description 过短无法判断功能。
- 硬编码路径：直接操作文件系统绝对路径而非通过 Vault API，破坏沙箱约定。
审核周期通常以周计，提交前对照官方 Developer Docs 的发布检查清单逐项自查，可以显著减少来回修改的次数。
常见问题
Q1：必须用 TypeScript 吗？
不是必须，纯 JavaScript 也可以，但官方类型定义对 TS 的支持最好，能避免大量 API 误用。社区模板默认是 TS，跟风成本最低。
Q2：插件能修改其他插件或 Obsidian 内部模块吗？
技术上可以通过访问内部对象实现，但依赖未公开 API 的代码在版本升级后极易失效，且审核会重点审查。尽量使用公开 API。
Q3：移动端和桌面端 API 有差异吗？
有。桌面端独有的能力（如 Electron 相关、部分 Node API）需要在isDesktopOnly声明或运行时做平台判断，否则移动端会报错。
Q4：开发中改了代码但没生效？
检查 esbuild 是否仍在运行、输出目录是否指向测试库的插件目录、Hot-Reload 是否正常触发。三者中任一环节断开都会导致"改了没反应"。
总结
Obsidian 插件开发的门槛集中在"理解三件套约定 + 掌握生命周期清理契约"这两点上，之后的三种扩展点（命令、设置、编辑器）按需递进即可。先在独立测试库跑通热重载流程，再对照审核清单打磨发布材料，是从个人玩具走向社区上架最短的一条路。
