大家好 
最近在整理 Cocos Creator 插件开发过程中遇到的一个老问题： 2.x 和 3.x 插件 API 差异太大，维护成本很高 。
为了解决这个问题，我封装并整理了一个 跨版本通用插件系统框架 ：
cc_extensions_tools_universal
GitHub： Cocos Creator 跨版本通用插件系统
今天简单跟大家分享一下这个插件系统的设计思路和使用方式，希望能对还在维护多版本插件的同学有所帮助 
一、背景 & 痛点
做过 Cocos 插件的同学应该都深有体会：
- Cocos Creator 2.x 和 3.x 编辑器 API 完全不同
- 同一个功能要写两套逻辑
- 到处都是
if (isV2) { ... } else { ... } - 后期维护和扩展非常痛苦
尤其是一些 通用工具型插件 （资源管理、构建辅助、自动化工具等），其实业务逻辑是一样的，但被版本差异拖累。
这个项目的目标只有一个：
让插件开发者只关心“做什么”，而不是“当前是 2.x 还是 3.x”
二、整体设计思路（重点）
这个插件系统的核心是 “抽象 + 适配” ，整体结构如下：
业务逻辑
↓
统一接口（Interface）
↓
版本工厂（Factory）
↓
V2 适配器 / V3 适配器
统一接口（最关键）
所有对外暴露的能力，都通过 统一接口 定义，例如：
- 打日志
- 操作资源
- 调用编辑器 API
- 扩展 Inspector 面板
业务层 永远只调用接口 ，不直接碰 Cocos API。
版本自动识别
系统会在启动时自动判断当前运行环境：
- Creator 2.x
- Creator 3.x
并交由 工厂类 创建对应版本的适配器。
开发者 无需手动判断版本 。
适配器模式
不同版本的 API 差异，被封装在对应的 Adapter 中：
XXXAdapterV2XXXAdapterV3
对外表现为 同一套方法签名 。
三、目前已经包含的功能模块
1. 跨版本插件基础框架
- 同一套插件代码
- 输出 v2 / v3 两套插件产物
- 构建流程已封装
2. 日志管理系统（强烈推荐）
内置统一的 LogManager ：
- 支持日志级别（info / warn / error）
- 支持模块区分
- 可一键关闭日志（适合发布版本）
LogManager.info("AssetTools", "开始扫描资源目录");
LogManager.error("Build", "构建失败");
3. 通用工具库
- 文件 / 目录操作
- 路径处理
- 配置读写
- 可直接在插件中复用
避免每个插件都手写一套 Node 工具代码。
4. Inspector 扩展示例
项目中已包含 Inspector 扩展的结构示例，支持：
- 自定义面板
- 属性扩展
- 多语言（i18n）
四、项目结构说明（精简版）
extensions_tools_universal/
├── assets/ # 游戏运行时通用工具（如日志）
├── src/
│ ├── core/ # 核心抽象 & 版本判断
│ ├── adapters/ # 2.x / 3.x 适配器
│ ├── tools/ # 通用工具库
│ ├── business/ # 插件业务示例
│ └── asset_directory/# Inspector UI 示例
├── dist/ # 构建后的插件产物
├── i18n/ # 多语言支持
└── 使用说明.md
五、实战示例：如何基于该系统写一个插件功能？
示例目标
实现一个“打印当前选中资源路径”的插件功能
（2.x / 3.x 通用）
Step 1：定义统一接口
// IAssetService.ts
export interface IAssetService {
getSelectedAssetPaths(): string[];
}
Step 2：分别实现 V2 / V3 适配器
// AssetServiceV2.ts
export class AssetServiceV2 implements IAssetService {
getSelectedAssetPaths(): string[] {
// 使用 Editor.Selection (2.x)
return [];
}
}
// AssetServiceV3.ts
export class AssetServiceV3 implements IAssetService {
getSelectedAssetPaths(): string[] {
// 使用 Editor.Selection (3.x)
return [];
}
}
Step 3：通过工厂获取实例
const assetService = ServiceFactory.getAssetService();
const paths = assetService.getSelectedAssetPaths();
paths.forEach(p => {
LogManager.info("Asset", p);
});
业务层 完全不关心当前是 2.x 还是 3.x
六、构建 & 使用方式
# 安装依赖
npm install
# 构建全部版本
npm run build
# 仅构建 2.x
npm run build:v2
# 仅构建 3.x
npm run build:v3
构建完成后，将对应目录拷贝到 Creator 的 extensions 目录即可使用。
七、适合哪些人使用？
非常适合：
-
正在维护 Cocos 2.x + 3.x 插件 的开发者 -
写工具类、自动化、编辑器增强插件的同学 -
希望插件结构更清晰、可维护性更高的人
八、最后
这个项目更像是一个 插件开发“地基” ，而不是具体功能插件：
- 你可以在它之上快速堆业务
- 也可以只拿走其中的跨版本架构思想
如果你也在被插件跨版本折磨，欢迎交流
有建议、问题、PR 都非常欢迎～
最后文档生成感谢(包括本主题):ChatGPT
