开发入门

概述

Obsidian 支持通过插件和主题进行扩展开发。本章节将介绍开发环境的搭建和基础知识。

开发环境准备

必需工具

• Node.js：v16 或更高版本
• npm 或 pnpm：包管理器
• 代码编辑器：推荐 VS Code
• Git：版本控制

安装 Node.js

# macOS/Linux (使用 nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Windows (使用 winget)
winget install OpenJS.NodeJS.LTS

# 验证安装
node --version
npm --version

推荐的 VS Code 插件

插件名称	用途
ESLint	代码检查
Prettier	代码格式化
TypeScript and JavaScript	语言支持
GitLens	Git 增强

创建插件项目

使用模板

推荐使用官方模板快速创建项目：

# 克隆模板
git clone https://github.com/obsidianmd/obsidian-sample-plugin my-plugin
cd my-plugin

# 安装依赖
npm install

# 或使用 degit
npx degit obsidianmd/obsidian-sample-plugin my-plugin

项目结构

my-plugin/
├── main.ts              # 插件入口文件
├── manifest.json        # 插件清单
├── styles.css          # 插件样式（可选）
├── tsconfig.json       # TypeScript 配置
├── esbuild.config.mjs  # 构建配置
├── package.json        # 项目配置
└── .github/            # GitHub Actions 配置

manifest.json

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "1.0.0",
  "description": "A sample Obsidian plugin",
  "author": "Your Name",
  "authorUrl": "https://github.com/yourusername",
  "isDesktopOnly": false
}

main.ts 基本结构

import { App, Plugin, PluginSettingTab, Setting } from 'obsidian';

// 定义设置接口
interface MyPluginSettings {
  mySetting: string;
}

// 默认设置
const DEFAULT_SETTINGS: MyPluginSettings = {
  mySetting: 'default value'
};

// 插件主类
export default class MyPlugin extends Plugin {
  settings: MyPluginSettings;

  async onload() {
    await this.loadSettings();

    // 注册命令
    this.addCommand({
      id: 'hello-command',
      name: 'Say Hello',
      callback: () => {
        console.log('Hello from my plugin!');
      }
    });

    // 添加设置面板
    this.addSettingTab(new MySettingTab(this.app, this));
  }

  onunload() {
    console.log('Plugin unloaded');
  }

  async loadSettings() {
    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
  }

  async saveSettings() {
    await this.saveData(this.settings);
  }
}

// 设置面板
class MySettingTab extends PluginSettingTab {
  plugin: MyPlugin;

  constructor(app: App, plugin: MyPlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  display(): void {
    const { containerEl } = this;
    containerEl.empty();

    new Setting(containerEl)
      .setName('Setting name')
      .setDesc('Setting description')
      .addText(text => text
        .setValue(this.plugin.settings.mySetting)
        .onChange(async (value) => {
          this.plugin.settings.mySetting = value;
          await this.plugin.saveSettings();
        }));
  }
}

开发流程

本地开发

1. 编译插件

   npm run dev

2. 链接到 Obsidian

   # macOS/Linux
   ln -s /path/to/my-plugin /path/to/vault/.obsidian/plugins/my-plugin
   
   # Windows (PowerShell)
   New-Item -ItemType SymbolicLink -Path "C:\path\to\vault\.obsidian\plugins\my-plugin" -Target "C:\path\to\my-plugin"

3. 在 Obsidian 中启用插件

   • 打开设置 → 第三方插件
   • 刷新插件列表
   • 找到并启用你的插件

热重载

修改代码后，需要重新加载插件：

• 方法一：禁用再启用插件
• 方法二：使用「Hot Reload」插件自动重载
• 方法三：Ctrl/Cmd + R 重新加载 Obsidian

调试

打开开发者工具：

• macOS：Cmd + Option + I
• Windows/Linux：Ctrl + Shift + I

// 使用 console.log 调试
console.log('Debug info', someVariable);

// 使用 console.error 记录错误
console.error('Something went wrong', error);

发布插件

准备发布

1. 更新 manifest.json 中的版本号
2. 构建生产版本

   npm run build

3. 确保包含必要文件
   • main.js
   • manifest.json
   • styles.css（如有）

发布到社区

1. 在 GitHub 创建仓库
2. 推送代码
3. 创建 Release，上传构建文件
4. Fork obsidian-releases 仓库
5. 编辑 community-plugins.json，添加你的插件信息
6. 提交 Pull Request

GitHub Release 配置

可以使用 GitHub Actions 自动构建：

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - '*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run build
      - uses: softprops/action-gh-release@v1
        with:
          files: |
            main.js
            manifest.json
            styles.css

TypeScript 配置

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "inlineSourceMap": true,
    "inlineSources": true,
    "module": "ESNext",
    "target": "ES6",
    "allowJs": true,
    "noImplicitAny": true,
    "moduleResolution": "node",
    "importHelpers": true,
    "isolatedModules": true,
    "strictNullChecks": true,
    "lib": ["DOM", "ES5", "ES6", "ES7"]
  },
  "include": ["**/*.ts"]
}

下一步

• 插件开发 - 深入学习插件开发
• 主题开发 - 学习主题开发
• API 参考 - 查阅 API 文档