chore: Add 插件版本兼容与升级方案.md

2026-04-05 03:38:36 +08:00 · 2024-09-09 21:39:27 +08:00
parent c2824a1bc8
commit aa6fa8d336
1 changed files with 128 additions and 0 deletions
--- a/docs/插件版本兼容与升级方案.md
+++ b/docs/插件版本兼容与升级方案.md
@@ -0,0 +1,128 @@
+### **插件版本兼容与升级方案**
+
+#### 1. **插件目录结构**
+为了确保插件管理的灵活性和兼容性，插件根据不同版本进行隔离，同时可以通过全局 `package.json` 标识兼容性。以下是目录结构示例：
+
+```
+- plugins/       // 全局插件目录，默认支持 v1
+- plugins.v2/    // v2 专用插件目录，管理与 v1 不兼容的插件
+  - package.json // v2 专用的 package.json，管理特定 v2 插件
+- plugins.v3/    // v3 专用插件目录，管理与 v1、v2 不兼容的插件
+  - package.json // v3 专用的 package.json，管理特定 v3 插件
+- package.json   // 全局 package.json，管理 v1、v2、v3 插件的兼容性
+```
+
+- **v1 项目**：使用 `plugins` 目录，加载全局插件，默认支持 v1 项目。
+- **v2 项目**：使用 `plugins.v2` 目录管理 v2 项目专用插件，并通过全局 `package.json` 检查多版本兼容插件。
+- **v3 项目**：使用 `plugins.v3` 目录管理 v3 项目专用插件，依次检查 `plugins.v2` 和全局 `package.json`。
+
+#### 2. **全局 `package.json` 插件管理**
+全局 `package.json` 文件管理插件的默认兼容性。所有插件默认支持 v1 项目，并通过 `v2: true` 和 `v3: true` 字段标识插件是否支持 v2 或 v3 项目。以下是示例：
+
+```json
+{
+  "CustomSites": {
+    "name": "自定义站点",
+    "description": "增加自定义站点为签到和统计使用。",
+    "labels": "站点",
+    "version": "1.0",
+    "icon": "world.png",
+    "author": "lightolly",
+    "level": 2,
+    "v2": true, // 适配 v2 版本
+    "v3": false, // 不适配 v3，明确标记
+    "history": {
+      "v1.2": "功能更新，提升性能",
+      "v1.1": "修复小问题",
+      "v1.0": "初始版本"
+    }
+  }
+}
+```
+
+#### 3. **版本专属 `package.json` 文件**
+为了管理 v2 和 v3 项目中的插件依赖，`plugins.v2` 和 `plugins.v3` 目录分别拥有自己的 `package.json` 文件，管理特定版本插件。这些插件可能与 v1 或其他版本不兼容，因此需要在各自版本中独立维护。
+
+- **v2 的 `package.json` 文件示例**：
+```json
+{
+  "CustomSites": {
+    "name": "自定义站点",
+    "description": "增加自定义站点为签到和统计使用。",
+    "labels": "站点",
+    "version": "1.0",
+    "icon": "world.png",
+    "author": "lightolly",
+    "level": 2,
+    "history": {
+      "v1.0": "初始版本"
+    }
+  }
+}
+```
+
+- **v3 的 `package.json` 文件示例**：
+```json
+{
+  "CustomSites": {
+    "name": "自定义站点",
+    "description": "增加自定义站点为签到和统计使用。",
+    "labels": "站点",
+    "version": "1.0",
+    "icon": "world.png",
+    "author": "lightolly",
+    "level": 2,
+    "history": {
+      "v1.0": "初始版本"
+    }
+  }
+}
+```
+
+#### 4. **插件加载与版本检测**
+
+##### **v1 项目**
+- 默认只从 `plugins` 目录加载插件，不进行任何版本筛选。
+- `package.json` 中的所有插件默认被视为兼容 v1 项目。
+
+##### **v2 项目**
+- **优先加载 `plugins.v2` 目录中的插件**，并依赖 `plugins.v2/package.json` 管理插件版本和依赖。
+- 如果插件在 `plugins.v2` 中不存在，则检查全局 `package.json` 中是否有标记 `v2: true` 的插件，并从全局 `plugins` 目录加载这些插件。
+
+##### **v3 项目**
+- **优先加载 `plugins.v3` 目录中的插件**，并依赖 `plugins.v3/package.json` 管理插件版本和依赖。
+- 如果插件在 `plugins.v3` 中不存在，则从 `plugins.v2` 目录加载插件。
+- 如果 `plugins.v2` 中也不存在，则检查全局 `package.json` 中标记 `v3: true` 的插件，并从全局 `plugins` 目录加载。
+
+#### 5. **插件冲突处理**
+当同一插件存在于多个目录时，插件加载按照以下优先级处理：
+
+- **v3 项目**：
+  - 优先加载 `plugins.v3` 目录中的插件。
+  - 若该插件不存在于 `plugins.v3` 中，则加载 `plugins.v2` 目录中的插件。
+  - 最后，若 `plugins.v2` 中也不存在，则从全局 `plugins` 目录加载并检查全局 `package.json` 中标记为 `v3: true` 的插件。
+
+- **v2 项目**：
+  - 优先加载 `plugins.v2` 目录中的插件。
+  - 若该插件不存在，则从全局 `plugins` 目录加载并检查全局 `package.json` 中标记为 `v2: true` 的插件。
+
+- **v1 项目**：
+  - 仅加载 `plugins` 目录中的全局插件，不涉及版本兼容性检查。
+
+#### 6. **插件升级与管理**
+- **v1 项目**：所有插件的升级和管理在全局 `package.json` 和 `plugins` 目录中进行。
+  
+- **v2 和 v3 项目**：
+  - 插件可以通过 `package.json` 中的 `v2: true` 和 `v3: true` 字段在多版本项目中共享。
+  - 插件也可以独立管理在 `plugins.v2` 或 `plugins.v3` 目录中，以确保版本专属插件不会影响其他版本项目。
+
+#### 7. **向后兼容性**
+- **v1 项目**：继续只从 `plugins` 目录加载全局插件，不受 `v2` 和 `v3` 插件的影响，确保向后兼容性。
+  
+- **v2 和 v3 项目**：通过独立的 `plugins.v2` 和 `plugins.v3` 目录管理专属插件，同时依赖全局 `package.json` 来处理跨版本兼容插件。
+
+---
+
+### **总结**
+该方案结合了全局和版本专属的插件管理策略，确保了插件在不同项目版本中的兼容性和灵活性。全局 `package.json` 管理多版本兼容插件，而 `plugins.v2` 和 `plugins.v3` 目录则为各自项目管理特定版本插件。通过插件加载优先级和独立的 `package.json` 文件，实现了高效的插件版本控制和向后兼容性。
+